Welcome

The Xbit API provides a comprehensive payment processing and cryptocurrency exchange platform. This API allows you to:

Accept Payments

Create and manage payments in UAH, KZT, and EUR with built-in commission calculation.

Process Withdrawals

Support card withdrawals, crypto withdrawals (BTC, USDT TRC20/ERC20), and code-based withdrawals.

Manage Account Data

Access balances, transaction history, and activation codes.

Handle Cryptocurrency

Calculate crypto amounts, get live exchange rates, and process crypto transactions.

Quick Start Guide

1. Get API Keys

API Keys are created by administrators through the admin panel. Each API Key consists of:

Component	Description
Public Key	Used in the `x-api-key` header to identify your application
Secret Key	Used to sign requests (keep this secure, never expose it!)
Permissions	Control which features your API key can access (`TOP_UP`, `WITHDRAW`, `ACCOUNT_DATA`)

2. Authentication

Every API request requires three headers:

Header	Value
`x-api-key`	YOUR_PUBLIC_KEY
`x-txc-payload`	BASE64_ENCODED_REQUEST_BODY
`x-txc-signature`	HMAC_SHA512_SIGNATURE

Create your request body with a nonce

Include nonce (current timestamp in milliseconds) in every request body:

    {
      "nonce": 1707484035123,
      "amountInCents": 10050,
      "currency": "UAH"
    }

Encode the body to Base64

Generate HMAC-SHA512 signature

Set all three headers in your request

Pass x-api-key, x-txc-payload, and x-txc-signature on every request.

3. Creating a Payment

Calculate the amount with commission

POST /v1/payment/calculate

Create the payment

POST /v1/payment

Redirect the user

Send the user to the paymentUrl returned in the response.

Receive webhook notification

Your configured webhookUrl will receive a push notification when the payment completes.

4. Creating a Withdrawal

For Card Withdrawal:

Calculate commission: POST /v1/withdraw/calculate-fiat

Create withdrawal: POST /v1/withdraw/card

For Crypto Withdrawal:

Calculate crypto amount: POST /v1/withdraw/calculate-crypto

Create withdrawal: POST /v1/withdraw/crypto

For Code Withdrawal:

Calculate commission: POST /v1/withdraw/calculate-fiat

Create withdrawal: POST /v1/withdraw/code

5. Checking Status

Payment status: POST /v1/payment/details

Withdrawal status: POST /v1/withdraw/details

6. Webhook Notifications

What are Webhooks?

Webhooks are asynchronous HTTP notifications sent automatically by the Xbit system to your server when important events occur, such as:

Payment completion (success or failure)

Withdrawal processing (status changes)

Instead of constantly polling our API to check status, webhooks push notifications to you in real-time.

Webhook Configuration

Configure your webhook URL in the UserApiKeys settings (via admin panel):

webhookUrl - The HTTPS endpoint on your server that will receive webhook notifications

All webhook events (payments and withdrawals) are sent to the same URL

Webhook Request Format

HTTP Method: POST

Headers:

Content-Type: application/json
x-api-key: YOUR_PUBLIC_KEY
x-txc-payload: BASE64_ENCODED_BODY
x-txc-signature: HMAC_SHA512_SIGNATURE

Authentication: Webhooks use the same authentication as API requests (signature verification). Always verify the signature to ensure the webhook came from Xbit!

Webhook Payload Examples

Payment Webhook

Sent when a payment status changes (typically from "new" to "success" or "fail"):

{
  "type": "payment",
  "data": {
    "paymentId": "43066701-0111-412c-8a0c-b8c06800449d",
    "status": "success",
    "amountInCents": 10050,
    "currencyId": "UAH",
    "codeId": "ABC123DEF456",
    "createdAt": "2026-02-12T10:30:00.000Z"
  }
}

Field Descriptions:

Field	Description
`type`	Webhook type, always `"payment"` for payment webhooks
`paymentId`	Unique payment identifier (UUID)
`status`	Payment status: `"new"`, `"success"`, or `"fail"`
`amountInCents`	Payment amount in cents
`currencyId`	Currency code (`UAH`, `KZT`, `EUR`)
`codeId`	Activation code ID (`null` if payment failed or not yet generated)
`createdAt`	Payment creation timestamp (ISO 8601)

Withdrawal Webhook

Sent when a withdrawal status changes:

{
  "type": "withdraw",
  "data": {
    "withdrawId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "success",
    "amountInCents": 100000,
    "currencyId": "UAH",
    "type": "card",
    "createdAt": "2026-02-12T10:30:00.000Z"
  }
}

Field Descriptions:

Field	Description
`type`	Webhook type, always `"withdraw"` for withdrawal webhooks
`withdrawId`	Unique withdrawal identifier (UUID)
`status`	Withdrawal status: `"new"`, `"notConfirmed"`, `"confirmed"`, `"busy"`, `"success"`, or `"fail"`
`amountInCents`	Withdrawal amount in cents
`currencyId`	Currency code
`type`	Withdrawal type: `"card"`, `"code"`, `"btc"`, `"usdtTrc20"`, or `"usdtErc20"`
`createdAt`	Withdrawal creation timestamp (ISO 8601)

Complete Webhook Example

Request:

POST https://your-site.com/webhook
Content-Type: application/json
x-api-key: your_public_key_abc123
x-txc-payload: eyJ0eXBlIjoicGF5bWVudCIsImRhdGEiOns...
x-txc-signature: a3f5c8e9b1d2f4a7c6e8d9f0b2a5c7e9f1d3a6...

Body:

{
  "type": "payment",
  "data": {
    "paymentId": "43066701-0111-412c-8a0c-b8c06800449d",
    "status": "success",
    "amountInCents": 10050,
    "currencyId": "UAH",
    "codeId": "ABC123DEF456",
    "createdAt": "2026-02-12T10:30:00.000Z"
  }
}

Webhook Retry Policy

If webhook delivery fails (non-2xx HTTP response, network error, or timeout), the system automatically retries sending the webhook.

Retry Schedule

The webhook will be retried at the following intervals:

1 minute after initial failure

5 minutes after previous attempt

10 minutes after previous attempt

15 minutes after previous attempt

And every 15 minutes 10 times

NOTE

Total retry attempts: 14 retries over approximately 3 hours

Merchant Recommendations

To ensure reliable webhook processing, follow these best practices:

1. Respond Quickly

Always respond with HTTP 200 as soon as you receive the webhook

Process the webhook asynchronously (queue it, then respond immediately)

Don't wait for database operations or external API calls before responding

Response timeout is typically 30 seconds

2. Handle Idempotently

Process webhooks idempotently - the same webhook may be delivered multiple times

Use paymentId or withdrawId to deduplicate events

Check if you've already processed this specific event before taking action

Store processed webhook IDs to prevent duplicate processing

3. Verify Signatures

Always verify the signature before processing webhooks

Use the same signature verification as API requests

Reject webhooks with invalid signatures (return 401)

4. Handle Duplicates

Due to retries, you may receive the same webhook multiple times

This is normal behavior - design your system to handle it gracefully

Example: If payment ABC is already marked as "success" in your database, ignore duplicate success webhooks

5. Implement Proper Error Handling

Return HTTP 200 only when you successfully received and queued the webhook

Return HTTP 5xx errors if your system is temporarily unavailable (we'll retry)

Log all webhook processing for debugging

6. Use HTTPS

Your webhook URL must use HTTPS (not HTTP)

Ensure your SSL certificate is valid

Webhooks to HTTP URLs may be rejected

Webhook Verification Example (Node.js)

Troubleshooting

Not receiving webhooks?

Check that your webhook URL is configured correctly in UserApiKeys

Ensure your server is accessible from the internet (not localhost)

Verify your SSL certificate is valid

Check your server logs for incoming requests

Make sure you're responding with HTTP 200

Receiving duplicate webhooks?

This is normal behavior due to retry logic

Implement idempotent processing using paymentId/withdrawId

Don't treat duplicates as errors

Webhooks timing out?

Respond with HTTP 200 immediately (within 1-2 seconds)

Move all processing to background jobs/queues

Don't wait for database operations before responding

Webhook requests use the same authentication (signature verification).

Important Notes

All amounts are in cents (e.g., 10050 cents = 100.50 UAH)

Nonce is required in every request (use Date.now() in JavaScript)

Rate limit: 60 requests per minute per IP address

All responses are wrapped in { data: {...} } format

Error responses include errorCode and descriptive messages

For EUR payments/withdrawals: Additional customer information is required (address, birthDate, etc.)

Response Format

Success Response:

{
  "data": {
    // Response data here
  }
}

Error Response:

{
  "data": {
    "msg": "Error description"
  },
  "errorCode": 1002
}

Error Codes Reference

All API errors follow a consistent format with an error code and descriptive message. Below is the complete list of error codes you may encounter when using the Xbit API.

Error Response Format

All errors return the following structure:

{
  "data": {
    "msg": "Human-readable error description",
    "field": "fieldName"
  },
  "errorCode": 1002
}

Complete Error Codes List

Code	Error Name	Description	Solution
1001	API_KEY_REQUIRED	API key header missing	Add `x-api-key` header to your request
1002	API_KEY_INVALID	Invalid or wrong API key	Check your public key is correct
1003	API_KEY_BLOCKED	API key is blocked	Contact administrator to unblock
1004	API_KEY_INACTIVE	API key is not active	Contact administrator to activate
1005	PAYLOAD_MISMATCH	Payload header doesn't match request body	Ensure payload header matches actual body
1006	SIGNATURE_REQUIRED	Signature header missing	Add `x-txc-signature` header
1007	PAYLOAD_HEADER_REQUIRED	Payload header missing	Add `x-txc-payload` header
1008	SIGNATURE_INVALID	Signature doesn't match expected value	Verify signature generation (HMAC-SHA512)
1009	TOP_UP_DISABLED	Top-up permission not enabled for API key	Enable TOP_UP permission for your API key
1010	API_GLOBALLY_DISABLED	API is globally disabled	Contact support
1011	ACTION_DISABLED	Required permission not enabled	Check API key permissions
1012	AMOUNT_NOT_DIVISIBLE	Amount must be divisible by 100 for this currency	Use amount divisible by 100 (see nearestLower/Higher)
1013	USER_VERIFICATION_REQUIRED	User needs KYC verification	Complete verification process
1014	INTERNAL_ERROR	Internal server error	Contact support with request details
1015	AMOUNT_TOO_LOW	Amount below minimum allowed	Increase amount to meet minimum
1016	AMOUNT_TOO_HIGH	Amount above maximum allowed	Decrease amount to meet maximum
1017	PAYMENT_NOT_FOUND	Payment doesn't exist or access denied	Verify payment ID and ownership
1018	API_DISABLED	API is disabled for this environment	Contact support
1019	CODE_ACTIVATION_FAILED	Code activation failed	Verify code is valid and not already used
1020	CODE_NOT_FOUND	Activation code doesn't exist	Check code value is correct
1021	PAYLOAD_ERROR	Request payload is invalid	Check request body structure
1022	CARD_VALIDATION_FAILED	Card number validation failed	Verify card number format
1023	MIN_CRYPTO_AMOUNTS_FAILED	Failed to get minimum crypto amounts	Contact support or try again later
1024	EXCHANGER_DISABLED	Cryptocurrency exchanger is disabled	Contact support
1025	BANKING_PROVIDER_ERROR	Banking provider error occurred	Contact support with transaction details
1026	PROVIDER_TEMPORARY_BLOCK	Provider payments temporarily blocked	Try again later or use different payment method
1027	CODE_ALREADY_REDEEMED	Code has already been used	Each code can only be used once
1028	WITHDRAW_NOT_FOUND	Withdrawal doesn't exist or access denied	Verify withdrawal ID and ownership

Common error scenarios

Authentication errors (1001–1008)

Error 1008 — SIGNATURE_INVALID (most common)

Cause: The HMAC-SHA512 signature doesn't match.

Solutions:

Verify you're using the correct secret key

Ensure the payload is exactly the same in the header and body

Check you're using HMAC-SHA512 (not SHA256)

Verify the payload is properly Base64 encoded

Make sure nonce is included in the request body

Permission errors (1009, 1011)

CAUTION

1009 TOP_UP_DISABLED — API key cannot create payments

1011 ACTION_DISABLED — API key lacks a specific feature permission

Contact your administrator to enable the required permissions.

Amount validation errors (1012, 1015, 1016)

Error 1012 — AMOUNT_NOT_DIVISIBLE

For certain payment providers (especially KZT), the final amount must be divisible by 100. The error response includes nearestLower and nearestHigher suggested amounts. Always use /payment/calculate first to validate amounts.

Errors 1015 / 1016 — AMOUNT_TOO_LOW / AMOUNT_TOO_HIGH

Each currency and operation type has minimum/maximum limits. Use the calculation endpoints to check limits before creating transactions.

Resource not found errors (1017, 1020, 1028)

CAUTION

1017 — Payment ID doesn't exist or belongs to another user

1020 — Activation code doesn't exist or is invalid

1028 — Withdrawal ID doesn't exist or belongs to another user

These errors also occur if you attempt to access resources belonging to a different user.

Code errors (1019, 1020, 1027)

Error 1027 — CODE_ALREADY_REDEEMED

Each activation code can only be used once. Check the code status with /account-data/code-details before attempting activation.

Support

For integration support, please refer to the complete API documentation or contact the support team.

Quick Start Guide#

1. Get API Keys#

2. Authentication#

3. Creating a Payment#

4. Creating a Withdrawal#

5. Checking Status#

6. Webhook Notifications#

What are Webhooks?#

Webhook Configuration#

Webhook Request Format#

Webhook Payload Examples#

Payment Webhook#

Withdrawal Webhook#

Complete Webhook Example#

Webhook Retry Policy#

Retry Schedule#

Merchant Recommendations#

1. Respond Quickly#

2. Handle Idempotently#

3. Verify Signatures#

4. Handle Duplicates#

5. Implement Proper Error Handling#

6. Use HTTPS#

Webhook Verification Example (Node.js)#

Troubleshooting#

Important Notes#

Response Format#

Error Codes Reference#

Error Response Format#

Complete Error Codes List#

Common error scenarios#

Authentication errors (1001–1008)#

Permission errors (1009, 1011)#

Amount validation errors (1012, 1015, 1016)#

Resource not found errors (1017, 1020, 1028)#

Code errors (1019, 1020, 1027)#

Support#

Quick Start Guide

1. Get API Keys

2. Authentication

3. Creating a Payment

4. Creating a Withdrawal

5. Checking Status

6. Webhook Notifications

What are Webhooks?

Webhook Configuration

Webhook Request Format

Webhook Payload Examples

Payment Webhook

Withdrawal Webhook

Complete Webhook Example

Webhook Retry Policy

Retry Schedule

Merchant Recommendations

1. Respond Quickly

2. Handle Idempotently

3. Verify Signatures

4. Handle Duplicates

5. Implement Proper Error Handling

6. Use HTTPS

Webhook Verification Example (Node.js)

Troubleshooting

Important Notes

Response Format

Error Codes Reference

Error Response Format

Complete Error Codes List

Common error scenarios

Authentication errors (1001–1008)

Permission errors (1009, 1011)

Amount validation errors (1012, 1015, 1016)

Resource not found errors (1017, 1020, 1028)

Code errors (1019, 1020, 1027)

Support