Pagos con Stablecoins

Una vez completado el onboarding, ya puedes empezar a aceptar pagos con SP Cuvex.
Aquí te mostramos los endpoints principales y cómo usarlos.

1. Crear un pago

Endpoint:

POST /v1/payments

Idempotencia

Para garantizar la creación segura de recursos, es obligatorio enviar el header x-idempotency-key:

Valor: UUID v4 generado por el cliente, único para cada nuevo recurso
Comportamiento:
- Mismo payload + misma key = retorna el objeto creado anteriormente
- Misma key + payload diferente = error HTTP 409
Duración: Las keys tienen validez de 24 horas

Ejemplo de request:

{
  "network": "TRON",
  "token": "USDT",
  "title": "My new payment",
  "description": "Purchase of food and groceries on March 3, 2025",
  "amount": "1234.56",
  "merchant_reference": "INV-25-AUG-0001",
  "validity_period": 20
}

Headers requeridos:

Content-Type: application/json
x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000

Ejemplo de respuesta:

{
  "message": "OK",
  "timestamp": "2024-04-16T17:44:51Z",
  "data": {
    "id": "263600a1-1514-4e57-a11d-be91e9c8e9d4",
    "merchant_reference": "INV-25-AUG-0001",
    "title": "My new payment",
    "description": "Purchase of food and groceries on March 3, 2025",
    "network": "TRON",
    "currency": "USDT",
    "amount": "1234.56",
    "confirmed_amount": "0",
    "status": "OPEN",
    "valid_until": 1755532150,
    "link": "https://dapp.example.sp.cuvex.io/payment?idsession=123456&amount=1234.56&contract=TVAKUM28o1pNj6pkcckvWHFUs1foRcSwAt",
    "created_at": "2024-04-16T17:44:51Z",
    "updated_at": "2024-04-16T17:44:51Z"
  }
}

Nota: El campo link es lo que debes presentar a tus clientes (como un botón, código QR, o cualquier método que prefieras) para proceder con el pago. Este enlace dirige a una dApp donde los clientes completan su pago usando su wallet preferida. Este enfoque garantiza compatibilidad con todos los tipos de wallet.

Ejemplos de código

Python
JavaScript
cURL

import requests
import uuid
import os

# Sandbox URL for testing - use production URL for live environment
url = "https://sp-dev.cuvex.io/ecommerce/v1/payments"

headers = {
    "Content-Type": "application/json",
    "x-idempotency-key": str(uuid.uuid4()),
    # Never hardcode API keys in source code - always use environment variables
    "x-api-key": os.getenv("API_KEY")
}

payload = {
    "network": "TRON",
    "token": "USDT",
    "title": "My new payment",
    "description": "Purchase of food and groceries on March 3, 2025",
    "amount": "1234.56",
    "merchant_reference": "INV-25-AUG-0001",
    "validity_period": 20
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const fetch = require('node-fetch');
const { v4: uuidv4 } = require('uuid');

// Sandbox URL for testing - use production URL for live environment
const url = 'https://sp-dev.cuvex.io/ecommerce/v1/payments';

const headers = {
    'Content-Type': 'application/json',
    'x-idempotency-key': uuidv4(),
    // Never hardcode API keys in source code - always use environment variables
    'x-api-key': process.env.API_KEY
};

const payload = {
    network: 'TRON',
    token: 'USDT',
    title: 'My new payment',
    description: 'Purchase of food and groceries on March 3, 2025',
    amount: '1234.56',
    merchant_reference: 'INV-25-AUG-0001',
    validity_period: 20
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

# Sandbox URL for testing - use production URL for live environment
# Never hardcode API keys in source code - always use environment variables
curl -X POST https://sp-dev.cuvex.io/ecommerce/v1/payments \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "network": "TRON",
    "token": "USDT",
    "title": "My new payment",
    "description": "Purchase of food and groceries on March 3, 2025",
    "amount": "1234.56",
    "merchant_reference": "INV-25-AUG-0001",
    "validity_period": 20
  }'

2. Consultar un pago

Endpoint:

GET /v1/payments/{paymentId}

Ejemplo de respuesta:

{
  "message": "OK",
  "timestamp": "2024-04-16T17:44:51Z",
  "data": {
    "id": "263600a1-1514-4e57-a11d-be91e9c8e9d4",
    "merchant_reference": "INV-25-AUG-0001",
    "title": "My new payment",
    "description": "Purchase of food and groceries on March 3, 2025",
    "network": "TRON",
    "currency": "USDT",
    "amount": "1234.56",
    "confirmed_amount": "0",
    "status": "OPEN",
    "valid_until": 1755532150,
    "link": "https://dapp.example.sp.cuvex.io/payment?idsession=123456&amount=1234.56&contract=TVAKUM28o1pNj6pkcckvWHFUs1foRcSwAt",
    "created_at": "2024-04-16T17:44:51Z",
    "updated_at": "2024-04-16T17:44:51Z"
  }
}

Ejemplos de código

Python
JavaScript
cURL

import requests
import os

# Sandbox URL for testing - use production URL for live environment
payment_id = "263600a1-1514-4e57-a11d-be91e9c8e9d4"
url = f"https://sp-dev.cuvex.io/ecommerce/v1/payments/{payment_id}"

headers = {
    # Never hardcode API keys in source code - always use environment variables
    "x-api-key": os.getenv("API_KEY")
}

response = requests.get(url, headers=headers)
print(response.json())

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

// Sandbox URL for testing - use production URL for live environment
const paymentId = '263600a1-1514-4e57-a11d-be91e9c8e9d4';
const url = `https://sp-dev.cuvex.io/ecommerce/v1/payments/${paymentId}`;

const headers = {
    // Never hardcode API keys in source code - always use environment variables
    'x-api-key': process.env.API_KEY
};

fetch(url, {
    method: 'GET',
    headers: headers
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

# Sandbox URL for testing - use production URL for live environment
# Never hardcode API keys in source code - always use environment variables
curl -X GET https://sp-dev.cuvex.io/ecommerce/v1/payments/263600a1-1514-4e57-a11d-be91e9c8e9d4 \
  -H "x-api-key: $API_KEY"

3. Listar pagos

Endpoint:

GET /v1/payments?page={page}&start_date={start_date}&end_date={end_date}

Los resultados se devuelven como una lista de pagos en orden cronológico inverso (más recientes primero), paginados en grupos de 25 registros por página.

Parámetros de consulta (opcionales):

page: Número de página (comenzando desde 0). Si no se especifica, se usa la página 0
start_date: Fecha inicial del rango en formato yyyy-mm-dd
end_date: Fecha final del rango en formato yyyy-mm-dd

Si no se especifican los filtros de fecha, se listan todos los pagos registrados.

Ejemplo de respuesta:

{
  "message": "OK",
  "timestamp": "2024-04-16T17:44:51Z",
  "data": {
    "total_count": 2551,
    "count": 25,
    "items": [
      {
        "id": "263600a1-1514-4e57-a11d-be91e9c8e9d4",
        "merchant_reference": "Payment-25-AUG-0001",
        "title": "My new payment",
        "network": "TRON",
        "currency": "USDT",
        "amount": "1234.56",
        "status": "OPEN",
        "valid_until": 1755532150,
        "created_at": "2024-04-16T17:44:51Z"
      }
    ]
  }
}

Ejemplos de código

Python
JavaScript
cURL

import requests
import os
from urllib.parse import urlencode

# Sandbox URL for testing - use production URL for live environment
base_url = "https://sp-dev.cuvex.io/ecommerce/v1/payments"

headers = {
    # Never hardcode API keys in source code - always use environment variables
    "x-api-key": os.getenv("API_KEY")
}

# Example with pagination and date filters
params = {
    "page": 0,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
}

url = f"{base_url}?{urlencode(params)}"
response = requests.get(url, headers=headers)
print(response.json())

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

// Sandbox URL for testing - use production URL for live environment
const baseUrl = 'https://sp-dev.cuvex.io/ecommerce/v1/payments';

const headers = {
    // Never hardcode API keys in source code - always use environment variables
    'x-api-key': process.env.API_KEY
};

// Example with pagination and date filters
const params = new URLSearchParams({
    page: '0',
    start_date: '2024-01-01',
    end_date: '2024-12-31'
});

const url = `${baseUrl}?${params}`;

fetch(url, {
    method: 'GET',
    headers: headers
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

# Sandbox URL for testing - use production URL for live environment
# Never hardcode API keys in source code - always use environment variables
# Example with pagination and date filters
curl -X GET "https://sp-dev.cuvex.io/ecommerce/v1/payments?page=0&start_date=2024-01-01&end_date=2024-12-31" \
  -H "x-api-key: $API_KEY"

4. Estados de pago

Los pagos en SP Cuvex pueden tener los siguientes estados durante su ciclo de vida:

Estados disponibles

Estado	Descripción
`OPEN`	Pago recién creado, en espera de confirmación de pago
`FINISHED`	Pago completado exitosamente con el monto exacto
`PARTIALLY_FILLED`	Pago recibido por un monto menor al especificado
`OVER_FILLED`	Pago recibido por un monto mayor al especificado
`EXPIRED`	Pago vencido sin recibir confirmación dentro del tiempo de validez
`LATE_PAYMENT`	Pago confirmado después del tiempo de validez especificado
`FAILED`	Error durante el procesamiento que impidió continuar

Flujo de estados

Flujo de estados de pago

Transiciones de estado

Al crear: todo pago inicia en estado OPEN
Confirmación exitosa: transición a FINISHED cuando se recibe el monto exacto
Confirmación parcial: transición a PARTIALLY_FILLED si el monto es menor al esperado
Sobrepago: transición a OVER_FILLED si el monto es mayor al esperado
Expiración: transición a EXPIRED si no hay confirmación en el tiempo límite
Pago tardío: transición a LATE_PAYMENT si llega confirmación después de expirar
Error: transición a FAILED ante cualquier error de procesamiento

5. Formato de decimales

SP Cuvex maneja todas las cantidades monetarias como strings para garantizar precisión en operaciones financieras:

Formato: punto decimal (.) como separador, sin separadores de miles
Ejemplos válidos: "1234.56", "0.000001", "1000000"
Decimales por token: dependerá de cada token. Por ejemplo, USDC y USDT permiten hasta un máximo de 6 decimales. Otros tokens pueden llegar a soportar hasta 18 decimales.

Importante: Este es el único formato aceptado en requests y retornado en responses.

6. Confirmación en tiempo real

SP Cuvex ofrece un webhook para recibir notificaciones de pagos en tiempo real.
Consulta la sección Webhook para aprender a implementarlo.

Consejo: además del webhook, puedes usar el endpoint de consulta de pago como mecanismo de respaldo.

1. Crear un pago​

Idempotencia​

Ejemplos de código​

2. Consultar un pago​

Ejemplos de código​

3. Listar pagos​

Parámetros de consulta (opcionales):​

Ejemplos de código​

4. Estados de pago​

Estados disponibles​

Flujo de estados​

Transiciones de estado​

5. Formato de decimales​

6. Confirmación en tiempo real​

1. Crear un pago

Idempotencia

Ejemplos de código

2. Consultar un pago

Ejemplos de código

3. Listar pagos

Parámetros de consulta (opcionales):

Ejemplos de código

4. Estados de pago

Estados disponibles

Flujo de estados

Transiciones de estado

5. Formato de decimales

6. Confirmación en tiempo real