ConexaPay — Documentación API

Visión general

ConexaPay es una pasarela crypto no-custodial para cobros en BSC y Polygon. Cada invoice genera una address única determinística (HD wallet), se monitorea on-chain y se marca PENDING → PAID con confirmaciones.

Base URL /api

https://conexapay.com/api

Health check: GET /health o GET /api/health

Networks & Assets EVM

BSC: USDT, BNB

Polygon: USDT, MATIC

Validación estricta por red

🏗️ Arquitectura: address única por invoice

ConexaPay asigna un wallet_index incremental y deriva una address determinística (HD) para cada invoice. El watcher revisa on-chain desde from_block para eficiencia.

Autenticación

ConexaPay usa API Keys por merchant en modo multi-merchant. Envía la key en el header:

Authorization: Bearer sk_live_tu_api_key_aqui

Multi-merchant Recomendado

Con API Key. Guarda merchant_id y snapshot completo (wallets, rate, webhook).

Legacy Pruebas

Sin API Key. Para pruebas / backwards compatibility.

Webhook Secret

Secreto por merchant para verificar que el webhook viene de ConexaPay. Firma HMAC SHA-256 (ready-to-enable).

Quick Start

Flujo recomendado: Crear invoice → Mostrar checkout → Confirmar por webhook

1. Crear invoice (cURL)

curl -X POST https://conexapay.com/api/invoice/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_tu_api_key" \
  -d '{
    "amount": 10,
    "network": "POLYGON",
    "asset": "USDT",
    "webhook_url": "https://tusitio.com/webhook"
  }'

2. Respuesta

{
  "id": "873cfa62-ff24-4daa-af13-e5b2a8d94d50",
  "amount": 10,
  "address": "0x8f3cf7e23c1b6c9a2d5e4f8b1a9c3d7e2f5a8b1c",
  "status": "PENDING",
  "network": "POLYGON",
  "asset": "USDT",
  "expires_at": "2026-02-16T23:59:39.192Z",
  "wallet_index": 26,
  "from_block": 8202923
}

3. Checkout hosted

https://conexapay.com/checkout.html?invoice=873cfa62-ff24-4daa-af13-e5b2a8d94d50

💡 Tip

Puedes usar tu checkout actual para "renderizar" la invoice con ?invoice= (deep-link) o construir tu propio checkout con los datos retornados.

Conceptos clave

Estados de una invoice

PENDING

Invoice creada, esperando pago on-chain. Monitoreo desde from_block.

PAID

Pago detectado y confirmado. Webhook enviado.

EXPIRED

TTL alcanzado (default 30 min). Ya no se aceptan pagos.

Confirmaciones

El watcher valida confirmaciones por red (ej: CONFIRMATIONS_BSC, CONFIRMATIONS_POLYGON). El evento PAID se marca cuando cumple las confirmaciones mínimas.

Create Invoice

POST /api/invoice/create — Crea una invoice con address única.

Campo	Tipo	Requerido	Descripción
`amount`	number	✅	Monto a cobrar (decimal)
`network`	string	✅	`BSC` o `POLYGON`
`asset`	string	✅	`USDT`, `BNB`, `MATIC`
`webhook_url`	string	❌	Fallback si el merchant no tiene webhook

Retrieve Invoice

GET /api/invoice/:id — Consulta el estado de una invoice.

curl https://conexapay.com/api/invoice/873cfa62-ff24-4daa-af13-e5b2a8d94d50

Webhooks

✅ Buenas prácticas

Idempotencia: manejar eventos duplicados
Verificar firma HMAC con webhook_secret
Guardar invoice_id y tx_hash como únicos

Payload estándar

{
  "event": "invoice.paid",
  "created_at": "2026-02-16T20:15:00Z",
  "data": {
    "id": "873cfa62-ff24-4daa-af13-e5b2a8d94d50",
    "status": "PAID",
    "amount": 10,
    "network": "POLYGON",
    "asset": "USDT",
    "address": "0x8f3cf7e23c1b6c9a2d5e4f8b1a9c3d7e2f5a8b1c",
    "tx_hash": "0x7a1c9e3d5f8b2a4c6e8d0f1a3b5c7e9d2f4a6b8c",
    "paid_at": "2026-02-16T20:14:45Z"
  }
}

Firma HMAC (próximamente)

Headers propuestos:

X-ConexaPay-Event: invoice.paid
X-ConexaPay-Timestamp: 1737576000
X-ConexaPay-Signature: sha256=...

Errores comunes

Error	HTTP	Descripción
`Invalid amount`	400	Monto inválido o ≤ 0
`Invalid network`	400	Network no soportada (BSC\|POLYGON)
`Asset not allowed`	400	Combinación red/asset inválida
`webhook_url inválida`	400	No inicia con http/https
`not_found`	404	Invoice inexistente
`internal_error`	500	Error interno del servidor

Ejemplos por lenguaje

Node.js

const apiKey = process.env.CONEXAPAY_API_KEY;

async function createInvoice() {
  const r = await fetch("https://conexapay.com/api/invoice/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      amount: 10,
      network: "POLYGON",
      asset: "USDT",
      webhook_url: "https://tusitio.com/webhook"
    })
  });
  
  const data = await r.json();
  return data; // id, address, expires_at
}

PHP

$apiKey = "sk_live_tu_api_key";
$url = "https://conexapay.com/api/invoice/create";

$payload = [
  "amount" => 10,
  "network" => "POLYGON",
  "asset" => "USDT",
  "webhook_url" => "https://tusitio.com/webhook"
];

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Bearer " . $apiKey
  ],
  CURLOPT_POSTFIELDS => json_encode($payload)
]);

$data = json_decode(curl_exec($ch), true);

Python

import requests

api_key = "sk_live_tu_api_key"
url = "https://conexapay.com/api/invoice/create"

r = requests.post(
    url,
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "amount": 10,
        "network": "POLYGON",
        "asset": "USDT",
        "webhook_url": "https://tusitio.com/webhook"
    }
)

data = r.json()
print(f"invoice_id: {data['id']}")

Roadmap 2026

🔏

Firmas HMAC

Headers estilo Stripe

⚙️

Auto‑settlement

Distribución automática

🧾

Metadata

order_id, customer

📦

SDKs

Node, PHP, Python

Construye con la pasarelano-custodial más simple

Visión general

Autenticación

Webhook Secret

Quick Start

1. Crear invoice (cURL)

2. Respuesta

3. Checkout hosted

Conceptos clave

Estados de una invoice

PENDING

PAID

EXPIRED

Confirmaciones

Create Invoice

Retrieve Invoice

Webhooks

Payload estándar

Firma HMAC (próximamente)

Errores comunes

Ejemplos por lenguaje

Node.js

PHP

Python

Roadmap 2026

Firmas HMAC

Auto‑settlement

Metadata

SDKs

Construye con la pasarela
no-custodial más simple