> ## Documentation Index
> Fetch the complete documentation index at: https://payer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete REST API reference for Card2Crypto

## Base URL

All API requests should be made to:

```
https://card2crypto.cc/api/v1
```

## Authentication

All API requests require authentication using your API key in the Authorization header:

```bash theme={null}
curl https://card2crypto.cc/api/v1/payments \
  -H "Authorization: Bearer c2c_live_your_api_key_here"
```

See [Authentication](/authentication) for details.

## API Keys

Get your API keys from the [Dashboard](https://card2crypto.cc/dashboard/shops).

API keys follow this format:

```
c2c_live_[64 character hex string]
```

<Warning>
  Never expose your API keys in client-side code, public repositories, or logs.
</Warning>

## Request Format

All POST requests must include:

* `Content-Type: application/json` header
* Valid JSON body

```bash theme={null}
curl -X POST https://card2crypto.cc/api/v1/payments \
  -H "Authorization: Bearer c2c_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "usd",
    "return_url": "https://yoursite.com/success"
  }'
```

## Response Format

### Success Response

All successful responses return JSON with a `data` field:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "pay_abc123",
    "amount": 10000,
    "currency": "usd",
    "status": "pending",
    "checkout_url": "https://card2crypto.cc/checkout/pay_abc123",
    "created_at": "2025-10-16T12:00:00Z"
  }
}
```

### Error Response

Error responses include an error message and appropriate HTTP status code:

```json theme={null}
{
  "success": false,
  "error": "Invalid API key"
}
```

HTTP status codes indicate the type of error:

* `400` - Bad Request (invalid parameters)
* `401` - Unauthorized (invalid or missing API key)
* `404` - Not Found (resource doesn't exist)
* `429` - Too Many Requests (rate limit exceeded)
* `500` - Internal Server Error

## Pagination

List endpoints support pagination using query parameters:

```bash theme={null}
GET /api/v1/payments?page=2&limit=20
```

Parameters:

* `page` - Page number (default: 1)
* `limit` - Items per page (default: 10, max: 100)

Response includes pagination metadata:

```json theme={null}
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}
```

## Rate Limits

API requests are rate limited to prevent abuse:

* **Production**: 100 requests per minute per API key
* Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1634567890
```

When rate limited, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "success": false,
  "error": "Rate limit exceeded. Try again in 30 seconds."
}
```

See [Rate Limits](/resources/rate-limits) for details.

## Idempotency

To prevent duplicate payments from network issues or retries, include an idempotency key:

```bash theme={null}
curl -X POST https://card2crypto.cc/api/v1/payments \
  -H "Authorization: Bearer c2c_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique_key_123" \
  -d '{
    "amount": 10000,
    "currency": "usd",
    "return_url": "https://yoursite.com/success"
  }'
```

Requests with the same idempotency key within 24 hours will return the same result without creating a duplicate payment.

## Versioning

The API version is included in the URL path:

```
https://card2crypto.cc/api/v1/...
```

We maintain backwards compatibility within major versions. Breaking changes will be released as new versions (v2, v3, etc.) with migration guides.

## Available Endpoints

### Payments

Create and manage payments:

<CardGroup cols={2}>
  <Card title="Create Payment" icon="plus" href="/api-reference/payments/create">
    POST /api/v1/payments
  </Card>

  <Card title="Retrieve Payment" icon="file-invoice-dollar" href="/api-reference/payments/retrieve">
    GET /api/v1/payments/:id
  </Card>
</CardGroup>

## SDK Libraries

Official SDKs coming soon. For now, use the REST API directly with your preferred HTTP client.

### Node.js

```javascript theme={null}
const fetch = require('node-fetch');

const apiKey = process.env.CARD2CRYPTO_API_KEY;

async function createPayment(amount, returnUrl) {
  const response = await fetch('https://card2crypto.cc/api/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount,
      currency: 'usd',
      return_url: returnUrl
    })
  });

  return response.json();
}
```

### PHP

```php theme={null}
<?php

function createPayment($amount, $returnUrl) {
    $apiKey = getenv('CARD2CRYPTO_API_KEY');

    $ch = curl_init('https://card2crypto.cc/api/v1/payments');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'amount' => $amount,
        'currency' => 'usd',
        'return_url' => $returnUrl
    ]));

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}
```

### Python

```python theme={null}
import os
import requests

def create_payment(amount, return_url):
    api_key = os.getenv('CARD2CRYPTO_API_KEY')

    response = requests.post(
        'https://card2crypto.cc/api/v1/payments',
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        },
        json={
            'amount': amount,
            'currency': 'usd',
            'return_url': return_url
        }
    )

    return response.json()
```

## Testing

See [Testing Guide](/resources/testing) for information on testing your integration.

## Support

Need help? Check these resources:

<CardGroup cols={2}>
  <Card title="Integration Guides" icon="book" href="/guides/nodejs">
    Step-by-step integration tutorials
  </Card>

  <Card title="FAQ" icon="question" href="/resources/faq">
    Frequently asked questions
  </Card>

  <Card title="Error Reference" icon="triangle-exclamation" href="/resources/errors">
    Complete list of error codes
  </Card>

  <Card title="Webhook Documentation" icon="webhook" href="/webhooks/overview">
    Learn how to handle payment notifications
  </Card>
</CardGroup>

## Changelog

Subscribe to API updates: [Dashboard > API Settings](https://card2crypto.cc/dashboard/shops)

Major changes will be announced at least 30 days in advance with migration guides provided.