Create Payment

Endpoint

POST /api/v1/payments

Creates a new payment and returns a checkout URL where customers can complete the payment.

Request

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Content-Type`	Yes	Must be `application/json`
`Idempotency-Key`	No	Unique key to prevent duplicate payments

Body Parameters

Parameter	Type	Required	Description
`amount`	integer	Yes	Payment amount in cents (e.g., 10000 = $100.00). Minimum: 50 ($ 0.50)
`currency`	string	Yes	Currency code. Currently only `"usd"` is supported
`return_url`	string	Yes	URL to redirect customer after payment completion
`customer_email`	string	No	Customer’s email address for receipts
`customer_name`	string	No	Customer’s name for receipts
`metadata`	object	No	Custom data to attach to this payment (max 50 keys)

Example Request

curl -X POST https://card2crypto.cc/api/v1/payments \
  -H "Authorization: Bearer c2c_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "usd",
    "return_url": "https://yoursite.com/success",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "metadata": {
      "order_id": "1234",
      "product": "Premium Plan"
    }
  }'

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "pay_abc123xyz789",
    "amount": 10000,
    "currency": "usd",
    "status": "pending",
    "checkout_url": "https://card2crypto.cc/checkout/pay_abc123xyz789",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "metadata": {
      "order_id": "1234",
      "product": "Premium Plan"
    },
    "created_at": "2025-10-16T12:00:00Z"
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique payment identifier
`amount`	integer	Payment amount in cents
`currency`	string	Currency code
`status`	string	Payment status: `pending`, `completed`, `failed`, or `refunded`
`checkout_url`	string	URL to redirect customer for payment
`customer_email`	string	Customer’s email (if provided)
`customer_name`	string	Customer’s name (if provided)
`metadata`	object	Custom data attached to payment
`created_at`	string	ISO 8601 timestamp when payment was created

Error Responses

400 Bad Request

Invalid parameters:

{
  "success": false,
  "error": "Amount must be at least 50 cents"
}

Common validation errors:

Amount less than 50 cents
Invalid currency (only USD supported)
Missing required fields
Invalid return_url format
Metadata exceeds 50 keys

401 Unauthorized

Invalid or missing API key:

{
  "success": false,
  "error": "Invalid API key"
}

Possible causes:

API key not provided in Authorization header
API key format is incorrect
API key doesn’t exist or was deleted
Shop is inactive

429 Too Many Requests

Rate limit exceeded:

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 30 seconds."
}

See Rate Limits for details.

500 Internal Server Error

Server error:

{
  "success": false,
  "error": "An unexpected error occurred"
}

If this persists, contact support.

Next Steps

After creating a payment:

Redirect customer to checkout_url

const payment = await createPayment();
window.location.href = payment.data.checkout_url;

Customer completes payment on the white-labeled checkout page
Customer redirected back to your return_url with payment ID:
```
https://yoursite.com/success?payment_id=pay_abc123xyz789
```
Webhook sent to your server with payment details (if configured)
Verify payment status by retrieving the payment:
```
GET /api/v1/payments/pay_abc123xyz789
```

Implementation Examples

Node.js / Express

const express = require('express');
const fetch = require('node-fetch');

const app = express();
const API_KEY = process.env.CARD2CRYPTO_API_KEY;

app.post('/create-payment', async (req, res) => {
  try {
    const { amount, email, name, orderId } = req.body;

    const response = await fetch('https://card2crypto.cc/api/v1/payments', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        amount: amount,
        currency: 'usd',
        return_url: `${req.protocol}://${req.get('host')}/success`,
        customer_email: email,
        customer_name: name,
        metadata: {
          order_id: orderId
        }
      })
    });

    const payment = await response.json();

    if (payment.success) {
      // Redirect customer to checkout
      res.redirect(payment.data.checkout_url);
    } else {
      res.status(400).json({ error: payment.error });
    }

  } catch (error) {
    console.error('Payment creation failed:', error);
    res.status(500).json({ error: 'Failed to create payment' });
  }
});

PHP

<?php

function createPayment($amount, $email, $name, $orderId) {
    $apiKey = getenv('CARD2CRYPTO_API_KEY');

    $data = [
        'amount' => $amount,
        'currency' => 'usd',
        'return_url' => 'https://yoursite.com/success',
        'customer_email' => $email,
        'customer_name' => $name,
        'metadata' => [
            'order_id' => $orderId
        ]
    ];

    $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($data));

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $result = json_decode($response, true);

    if ($httpCode === 200 && $result['success']) {
        // Redirect to checkout
        header('Location: ' . $result['data']['checkout_url']);
        exit;
    } else {
        throw new Exception($result['error'] ?? 'Failed to create payment');
    }
}

// Usage
try {
    createPayment(10000, 'customer@example.com', 'John Doe', '1234');
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

Python / Flask

import os
import requests
from flask import Flask, request, redirect

app = Flask(__name__)
API_KEY = os.getenv('CARD2CRYPTO_API_KEY')

@app.route('/create-payment', methods=['POST'])
def create_payment():
    try:
        data = request.json

        response = requests.post(
            'https://card2crypto.cc/api/v1/payments',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'amount': data['amount'],
                'currency': 'usd',
                'return_url': request.url_root + 'success',
                'customer_email': data.get('email'),
                'customer_name': data.get('name'),
                'metadata': {
                    'order_id': data['order_id']
                }
            }
        )

        payment = response.json()

        if payment['success']:
            return redirect(payment['data']['checkout_url'])
        else:
            return {'error': payment['error']}, 400

    except Exception as e:
        return {'error': str(e)}, 500

Metadata Usage

Use metadata to attach custom data to payments. This data is returned in webhooks and when retrieving payments.

Best Practices

// Good - Store identifiers to link with your system
{
  "metadata": {
    "order_id": "1234",
    "user_id": "5678",
    "product_id": "premium_plan",
    "subscription_period": "monthly"
  }
}

// Bad - Don't store sensitive data
{
  "metadata": {
    "credit_card": "4242...",      // Never!
    "password": "secret123",        // Never!
    "api_key": "sk_live_..."       // Never!
  }
}

Metadata Limits

Maximum 50 keys per payment
Keys must be strings
Values must be strings, numbers, or booleans
Total metadata size limit: 5KB

Idempotency

Prevent duplicate payments by including an idempotency key:

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

Benefits:

Safe to retry failed requests
Prevents duplicate charges if request times out
Guarantees exactly-once payment creation

Keys expire after 24 hours.

Testing

Use real API keys to create test payments with small amounts ($0.50 minimum). See Testing Guide for details.

Retrieve Payment

Check payment status after creation

Webhook Overview

Get real-time payment notifications

Node.js Guide

Complete integration tutorial

Error Reference

Complete list of error codes

API Documentation

Payments

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success Response (200 OK)

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

500 Internal Server Error

Next Steps

Implementation Examples

Node.js / Express

PHP

Python / Flask

Metadata Usage

Best Practices

Metadata Limits

Idempotency

Testing

Retrieve Payment

Webhook Overview

Node.js Guide

Error Reference

API Documentation

Payments

​Endpoint

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success Response (200 OK)

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​429 Too Many Requests

​500 Internal Server Error

​Next Steps

​Implementation Examples

​Node.js / Express

​PHP

​Python / Flask

​Metadata Usage

​Best Practices

​Metadata Limits

​Idempotency

​Testing

​Related Resources

Retrieve Payment

Webhook Overview

Node.js Guide

Error Reference

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success Response (200 OK)

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

500 Internal Server Error

Next Steps

Implementation Examples

Node.js / Express

PHP

Python / Flask

Metadata Usage

Best Practices

Metadata Limits

Idempotency

Testing

Related Resources