Documentación para desarrolladores

Documentación API de Buyesia Pay

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

Base URL
https://dev.buyesia.com
Moneda base: stablecoins USDT y USDC. Consulta /merchant/api/available-currencies para conocer las monedas que acepta tu checkout.
Registrarse para obtener credenciales
POST /merchant/api/verify GET /merchant/api/available-currencies POST /merchant/api/transaction-info WEBHOOK X-Webhook-Signature BASE USDT / USDC

Resumen

La integración se apoya en tres endpoints públicos para autenticar, consultar las monedas disponibles 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. Consulta las monedas

GET /merchant/api/available-currencies

Consulta qué monedas acepta tu checkout antes de crear la transacción.

4. 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://dev.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://dev.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": "7fKpQ2mXvL9sR4tN6wY8aBcDeF"
  }
}

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.

Monedas disponibles

Antes de crear un cobro, consulta las monedas que el checkout del merchant puede aceptar según sus métodos activos.

GET https://dev.buyesia.com/merchant/api/available-currencies

Requiere Authorization: Bearer {access_token}. Devuelve las monedas soportadas (USDT o USDC) junto con los métodos de checkout disponibles. Usa el código devuelto en el campo currency de transaction-info.

Solicitud cURL
curl -X GET https://dev.buyesia.com/merchant/api/available-currencies \
  -H "Authorization: Bearer {access_token}"
Respuesta JSON
{
  "status": "success",
  "message": "Available checkout currencies loaded successfully.",
  "data": {
    "currencies": [
      {
        "code": "USDT",
        "name": "Tether USD",
        "symbol": "₮",
        "is_default": true,
        "checkout_methods_count": 2,
        "checkout_methods": [
          {
            "key": "bpay",
            "display_name": "Buyesia Pay",
            "behavior": "custodial",
            "is_default": true
          }
        ]
      }
    ]
  }
}

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://dev.buyesia.com/merchant/api/transaction-info

Requiere Authorization: Bearer {access_token}. Envía una moneda soportada por tu checkout (consulta /merchant/api/available-currencies) 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. USDT o USDC, según lo que devuelva /merchant/api/available-currencies para tu checkout.
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 No Identificador externo de tu orden.
item_name string No 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://dev.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://dev.buyesia.com/merchant/checkout/sandbox/demo_token_123",
    "webUrl": "https://dev.buyesia.com/merchant/checkout/sandbox/demo_token_123",
    "appUrl": "bpay://merchant/checkout/demo_token_123",
    "intentUrl": "intent://merchant/checkout/demo_token_123#Intent;scheme=bpay;package=com.buyesia.pay;end",
    "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. El checkout alojado muestra únicamente los métodos de pago y redes disponibles para la moneda de la orden.

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]);