Documentación para desarrolladores

Documentación API de Buyesia Pay

Integra Buyesia Pay con la API REST actual, crea transacciones en USDT y procesa confirmaciones firmadas por webhook.

Base URL
https://www.pay.buyesia.com
Moneda base: USDT. Todas las transacciones se procesan en USDT.
Registrarse para obtener credenciales
POST /merchant/api/verify POST /merchant/api/transaction-info WEBHOOK X-Webhook-Signature BASE USDT

Resumen

La integración se apoya en dos llamadas principales para autenticar y crear la transacción, más un webhook firmado para confirmar eventos de pago.

1. Autentica

POST /merchant/api/verify

Envía client_id y client_secret para obtener un access_token temporal.

2. Crea el pago

POST /merchant/api/transaction-info

Crea la intención de cobro y devuelve approvedUrl para redirigir al checkout.

3. Procesa webhooks

X-Webhook-Signature

Valida la firma HMAC del payload antes de marcar el pago como confirmado.

Autenticación

Todas las solicitudes privadas requieren autenticación mediante credenciales de comercio generadas desde el panel de administración.

Registrarse para obtener credenciales
POST https://www.pay.buyesia.com/merchant/api/verify

Envía client_id y client_secret para validar el merchant y obtener data.access_token.

Solicitud cURL
curl -X POST https://www.pay.buyesia.com/merchant/api/verify \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "tu_client_id",
    "client_secret": "tu_client_secret"
  }'
Respuesta JSON
{
  "status": "success",
  "message": "Client Verified",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.demo"
  }
}

Entornos

Buyesia Pay ofrece sandbox y live con el mismo contrato de API, pero con credenciales y comportamiento operativo distintos.

Entorno Uso Credenciales Procesa pagos reales
Sandbox Desarrollo y pruebas test_* No - Simula el pago sin mover fondos
Live Producción Credenciales live del comercio Sí - Procesa pagos reales
Importante: Las credenciales sandbox usan el prefijo test_ y simulan el flujo completo de pago. El checkout muestra un banner de modo prueba y no mueve fondos reales.

Crear pago

Crea una transacción para que tu cliente complete el checkout alojado y luego redirige al approvedUrl devuelto por la API.

POST https://www.pay.buyesia.com/merchant/api/transaction-info

Requiere Authorization: Bearer {access_token}. La moneda base es USDT y los parámetros de retorno deben ser URLs públicas válidas.

Campo Tipo Requerido Descripción
amount number Sí Monto mayor a 0.
currency string Sí Código de moneda. Siempre USDT.
successUrl string Sí URL del merchant a la que se redirige al completar el pago.
cancelUrl string Sí URL del merchant para pagos cancelados o interrumpidos.
order_no string Sí Identificador externo de tu orden.
item_name string Sí Nombre o descripción visible del producto o servicio.
webhook_url string No URL para eventos transaction.created, payment.success y transaction.failed.
metadata object No Objeto libre que se reenvía en el webhook.
Solicitud cURL
curl -X POST https://www.pay.buyesia.com/merchant/api/transaction-info \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USDT",
    "successUrl": "https://tu-sitio.com/success",
    "cancelUrl": "https://tu-sitio.com/cancel",
    "order_no": "ORD-2026-1001",
    "item_name": "Suscripcion Pro",
    "webhook_url": "https://tu-sitio.com/webhook",
    "metadata": {
      "customer_id": "cus_128",
      "plan": "pro"
    }
  }'
Respuesta JSON
{
  "status": "success",
  "message": "Transaction Info Created Successfully!",
  "data": {
    "approvedUrl": "https://www.pay.buyesia.com/merchant/checkout/sandbox/demo_token_123",
    "checkout_token": "demo_token_123",
    "grant_id": 18354021,
    "token": "Cj2mMNt5sE7P9dZrQa4K",
    "amount": "100.00",
    "currency": "USDT",
    "order_no": "ORD-2026-1001",
    "item_name": "Suscripcion Pro",
    "status": "pending",
    "payment_method": null,
    "metadata": {
      "customer_id": "cus_128",
      "plan": "pro"
    }
  }
}
Redirige al cliente a data.approvedUrl para completar el pago.

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta y valida siempre la firma del payload antes de procesarlo.

Eventos disponibles:
  • transaction.created - Transacción creada exitosamente
  • payment.success - Pago completado exitosamente
  • transaction.failed - Transacción fallida
Estructura del webhook
{
  "event": "payment.success",
  "payload": {
    "transaction_id": "f8e4af91-9946-469f-b3cf-7b5b8a35d4e3",
    "order_no": "ORD-2026-1001",
    "item_name": "Suscripcion Pro",
    "metadata": {
      "customer_id": "cus_128",
      "plan": "pro"
    },
    "amount": 100,
    "currency": "USDT",
    "status": "success",
    "timestamp": "2026-03-29T09:45:18+00:00"
  },
  "timestamp": 1774777518
}
Verificar firma
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$clientSecret = 'tu_client_secret';

$expectedSignature = hash_hmac('sha256', $rawBody, $clientSecret);

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    echo json_encode(['error' => 'Firma invalida']);
    exit;
}

$payload = json_decode($rawBody, true);
$event = $payload['event'] ?? null;
$data = $payload['payload'] ?? [];

if ($event === 'payment.success') {
    // Marca tu orden como pagada usando $data['order_no'] o $data['transaction_id']
}

http_response_code(200);
echo json_encode(['received' => true]);