API Documentation – CryptoGap

🔒 Authentication

All API requests must include your API key in the X-API-Key header.

Generate API keys from your Settings page. Keys are prefixed with cgk_ and are shown only once at creation time.

# Include your API key in every request
curl -H "X-API-Key: cgk_your_api_key_here" \
     https://cryptogap.com/api/v1/payments

⚡ Quick Start

Create a payment and redirect your customer to the pay link in 3 steps:

# 1. Create a payment
curl -X POST https://cryptogap.com/api/v1/payments \
  -H "X-API-Key: cgk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Order #1234",
    "amount_usd": 49.99,
    "description": "Premium Plan - Monthly"
  }'

# 2. Get the pay_url from the response and redirect your customer to it
# Response: { "payment": { "pay_url": "https://cryptogap.com/pay/abc123", ... } }

# 3. Poll the payment status to confirm payment
curl https://cryptogap.com/api/v1/payments/abc123 \
  -H "X-API-Key: cgk_your_api_key"

Create Payment

POST /api/v1/payments

Create a new payment request. Returns a payment object with a pay_url you can redirect customers to.

Request Body (JSON)

Parameter	Type	Description
`title` REQUIRED	string	Payment title shown to the payer (e.g. "Order #1234")
`amount_usd` REQUIRED	number	Amount in USD (must be > 0)
`description` optional	string	Longer description shown to the payer
`kyc_method` optional	string	`"id_upload"` (default) or `"bankid"`
`allow_bankid` optional	boolean	Allow BankID as alternative KYC method (default: false)
`fee_paid_by` optional	string	`"merchant"` (default) or `"payer"`
`metadata` optional	object	Custom key-value pairs for your reference (e.g. `{"order_id": "123"}`)

Example Response (201)

{
  "success": true,
  "payment": {
    "id": "a1b2c3d4-...",
    "short_code": "xY9kL2mN",
    "title": "Order #1234",
    "amount_usd": 49.99,
    "amount_received_usd": 0.0,
    "status": "kyc_required",
    "pay_url": "https://cryptogap.com/pay/xY9kL2mN",
    "fee_usd": 0.50,
    "fee_paid_by": "merchant",
    "fee_free_tier": false,
    "kyc_status": "not_started",
    "created_at": "2026-03-09T14:30:00+00:00",
    "expires_at": "2026-03-19T14:30:00+00:00",
    ...
  }
}

Get Payment

GET /api/v1/payments/{id_or_short_code}

Retrieve a payment by its UUID or short code. Use this to check whether a payment has been completed.

Key Response Fields

Field	Description
`status`	Current payment status (see statuses)
`amount_usd`	Requested amount in USD
`amount_received_usd`	Amount received so far in USD
`pay_url`	URL to redirect the payer to
`selected_coin`	Which cryptocurrency the payer selected (null until chosen)
`wallet_address`	Generated wallet address for the payment
`kyc_status`	KYC verification status
`fee_usd`	Platform fee amount
`overpaid_usd`	Amount overpaid (if any)

List Payments

GET /api/v1/payments

List all your payments, optionally filtered by status.

Query Parameters

Parameter	Type	Description
`status` optional	string	Filter by status: `paid`, `pending`, `kyc_required`, etc.
`limit` optional	int	Max results, 1–200 (default: 50)
`offset` optional	int	Pagination offset (default: 0)

# Get all paid payments
curl "https://cryptogap.com/api/v1/payments?status=paid&limit=20" \
  -H "X-API-Key: cgk_your_api_key"

Cancel Payment

POST /api/v1/payments/{id_or_short_code}/cancel

Cancel a payment request. Cannot cancel payments that are already paid or overpaid.

📊 Payment Statuses

Status	Description
`kyc_required`	Waiting for the payer to complete identity verification
`pending`	KYC approved, waiting for crypto payment
`partially_paid`	Some crypto received but not the full amount
`paid`	Full amount received — payment complete
`overpaid`	More than the requested amount was received
`expired`	Payment expired (10-day window elapsed)
`cancelled`	Cancelled by the merchant
`refunded`	Partial payment refunded after expiry

💡 To check if a payment is complete, look for status == "paid" or status == "overpaid".

🔗 Embed Pay Link

After creating a payment via the API, use the pay_url from the response to redirect your customer to complete payment.

Checkout Integration (HTML)

<!-- Redirect button -->
<a href="https://cryptogap.com/pay/YOUR_SHORT_CODE"
   class="pay-button">
   Pay with Crypto
</a>

<!-- Or embed in an iframe -->
<iframe src="https://cryptogap.com/pay/YOUR_SHORT_CODE"
        width="100%" height="700"
        frameborder="0">
</iframe>

Checkout Flow

# Server-side: create payment and get the pay URL
response = requests.post(
    "https://cryptogap.com/api/v1/payments",
    headers={"X-API-Key": API_KEY},
    json={
        "title": f"Order #{order.id}",
        "amount_usd": order.total,
        "metadata": {"order_id": str(order.id)},
    }
)
pay_url = response.json()["payment"]["pay_url"]

# Redirect the customer to pay_url
return redirect(pay_url)

⚠️ Error Handling

All error responses follow this format:

{
  "detail": "Description of the error"
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created (new payment)
`400`	Bad request (missing or invalid parameters)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (account disabled)
`404`	Payment not found

💻 Code Examples

Python

import requests

API_KEY = "cgk_your_api_key"
BASE_URL = "https://cryptogap.com/api/v1"
headers = {"X-API-Key": API_KEY}

# Create a payment
resp = requests.post(f"{BASE_URL}/payments", headers=headers, json={
    "title": "Order #1234",
    "amount_usd": 49.99,
})
payment = resp.json()["payment"]
print(f"Pay URL: {payment['pay_url']}")

# Check if paid
resp = requests.get(f"{BASE_URL}/payments/{payment['short_code']}", headers=headers)
status = resp.json()["payment"]["status"]
if status in ("paid", "overpaid"):
    print("Payment complete!")

JavaScript (Node.js)

const API_KEY = "cgk_your_api_key";
const BASE_URL = "https://cryptogap.com/api/v1";

// Create a payment
const res = await fetch(`${BASE_URL}/payments`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Order #1234",
    amount_usd: 49.99,
  }),
});
const { payment } = await res.json();
console.log(`Pay URL: ${payment.pay_url}`);

// Check if paid
const check = await fetch(`${BASE_URL}/payments/${payment.short_code}`, {
  headers: { "X-API-Key": API_KEY },
});
const data = await check.json();
if (["paid", "overpaid"].includes(data.payment.status)) {
  console.log("Payment complete!");
}

PHP

$apiKey = "cgk_your_api_key";
$baseUrl = "https://cryptogap.com/api/v1";

// Create a payment
$ch = curl_init("$baseUrl/payments");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: $apiKey",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "title" => "Order #1234",
    "amount_usd" => 49.99,
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
$payUrl = $response["payment"]["pay_url"];

// Redirect customer
header("Location: $payUrl");

📖 API Documentation