API Reference

Overview

Crypto Pay is a powerful solution designed for Payment Aggregators and Corporate Clients (Merchants) to seamlessly integrate cryptocurrency payments into their operations. This platform enables merchants to accept crypto payments for goods and services or deposit funds using digital assets.

Key features include:

• Pay in crypto – Accept cryptocurrency from customers.
• Withdraw in crypto – Convert fiat balances into crypto and send to external wallets.

Whether you're building a full payment gateway or integrating direct merchant capabilities, Crypto Pay provides the tools needed for efficient, secure, and scalable crypto transactions.

👉 Discover how to integrate advanced crypto payment flows with powerful tools and real-time processing.

Base URL and API Methods

The base URL for all production API requests is:
https://api.cryptopayx.tech

For sandbox testing, use:
https://api.sandbox.cryptopayx.tech

Crypto Pay follows RESTful design principles and supports standard HTTP methods:

• GET – Retrieve resources.
• POST – Create new resources.
• PUT – Update existing resources.
• DELETE – Remove resources.

Request Parameters

You can pass parameters in two ways:

• As a query string (required for GET).
• In the request body with application/json content type (optional for POST, PUT, DELETE).

Parameters may be mixed between query strings and request bodies. If a parameter appears in both, the query string value takes precedence.

All timestamps are in milliseconds since Unix Epoch.

Responses return data in chronological order, with the newest entries first.

Authentication

To access protected endpoints, you must generate an API Key and Secret. Starting December 9, 2024, users can manage these credentials directly from the Client Area under Security Settings.

Available actions:

• Generate a new key pair (one per account).
• Delete the current API key.
• Reset (delete and regenerate).

Ensure you replace placeholder values in code examples with your actual credentials.

Required Headers

All authenticated requests must include:

Signing Requests

The signature ensures request integrity and authenticity. It's generated as follows:

HMAC_SHA256(apiSecret, timestamp + method + path + contentHash)

Where:

• timestamp: Same as CRYPTO-PAY-API-TIMESTAMP
• method: Uppercase HTTP method (POST, GET, etc.)
• path: Request path without query parameters
• contentHash: Base64-encoded SHA256 hash of request body (empty for GET)

The timestamp must be within 60 seconds of server time.

Return Codes

Payment Intents

A payment intent represents a request to deposit a specific amount of cryptocurrency into a merchant’s wallet. It supports cross-currency deposits with automatic conversion.

Creation Methods

1. Via API – Fully programmatic integration.
2. Via iframe – Embedded UI for simplified checkout.
3. Payment Request Link – Shareable link without integration.

👉 Learn how to implement secure, scalable payment intent systems with minimal friction.

Payment Intent Statuses

Payment intents progress through various states based on user action and system logic:

See full status grid below for flow-specific conditions.

Handling Failed or Mismatched Payments

When a payment fails due to incorrect amounts or timeouts, several recovery options exist:

Automatic Retry

If the received amount falls within the configured threshold (e.g., ±2%), the system automatically retries the transaction with updated pricing.

Manual Retry

For failed intents where conversion is enabled, merchants can manually retry using the current market rate.

Refund

Funds can be refunded via API or UI. Optionally, generate a refund link for customers to submit their wallet details.

Accept Received Amount

Merchants may manually accept under/over payments and complete the intent accordingly.

Top-Up (Underpaid Intent)

Multiple deposits are allowed until the total meets the required amount or threshold.

Sandbox Testing

Use the sandbox environment to simulate all payment flows without real transactions.

Sandbox Base URL:
https://api.sandbox.cryptopayx.tech

Sandbox accounts are separate from live accounts and require unique API keys.

Test Flows Overview

Each flow includes detailed webhook notifications for status tracking.

Core Endpoints

List Supported Currencies & Networks

GET /v1/currencies

Returns all available coins, networks, and virtual fiat currencies (e.g., SAR, AED).

Request Quote

POST /v2/payment-intents/estimated-quote

Get estimated conversion rates before creating a payment intent.

Create Payment Intent

POST /v2/payment-intents/

Initiate a new payment with specified currency, amount, network, and callback URL.

Check Status

GET /v1/payment-intents/{paymentIntentId}

Retrieve real-time status and transaction details.

Search by Filters

POST /v1/payment-intents/search

Filter by customOrderId, accountId, or date range.

Payouts

Convert fiat balances to cryptocurrency and withdraw to external wallets.

Supported methods:

• API-driven payouts
• Iframe-based withdrawal interface

Status progression:
Pending → Processing → Completed (or Failed)

Notifications are sent on every status change.

Single Payment Address Mode

For integration simplicity, enable a single permanent crypto address for multiple payment intents under one account.

To activate:

• Enable via customer request.
• Include accountId when creating intents.
• Omitting accountId disables this mode regardless of settings.

Crypto Pay identifies deposits by matching incoming transactions to active intents using account metadata.

Conversion Rules

Customize how incoming crypto is handled:

• Disable Conversion: Keep funds in original cryptocurrency.
• Convert to Specific Currency: Auto-convert to selected fiat or crypto.
• Convert to Intent Currency: Use currency defined at creation (USD, EUR, GBP).

Exceptions can be set for specific coins that should never convert.

Virtual Fiat Currencies

Support for virtual fiat includes:

• SAR (Saudi Riyal)
• AED (UAE Dirham)
• INR (Indian Rupee)
• EGP (Egyptian Pound)
• QAR (Qatari Riyal)

These allow merchants to quote prices in local currencies while receiving crypto settlements.

Frequently Asked Questions

What is a payment intent?

A payment intent is a secure request to receive cryptocurrency from a customer. It includes amount, currency, network, and destination details.

How do I test integrations safely?

Use the sandbox environment at https://api.sandbox.cryptopayx.tech with test credentials to simulate all transaction scenarios without real funds.

Can I accept partial payments?

Yes. If enabled, multiple deposits can fulfill a single intent. The system tracks totals and allows top-ups until requirements are met.

How does automatic retry work?

If a deposit deviates slightly from the requested amount but stays within the configured threshold (e.g., ±2%), the system automatically retries processing with adjusted pricing.

What happens if no payment is made?

After 30 seconds with no deposit, the intent fails. However, if a valid deposit arrives later and meets threshold rules, the status updates to "Completed".

Can I refund a failed payment?

Yes. Refunds can be issued via API or through a customer-facing refund link that allows users to enter their wallet information securely.

👉 Explore next-generation crypto payment infrastructure with seamless integration and enterprise-grade security.