API REST

API REST Documentation

Integra Buyesia Pay en tu aplicación usando nuestra API REST sin necesidad de SDK. Autenticación segura, webhooks en tiempo real y documentación completa.

REST
Contenido

Descripción General

La API REST de Buyesia Pay te permite integrar pagos directamente en tu aplicación. Esta API proporciona endpoints para autenticación, creación de transacciones y recepción de webhooks en tiempo real.

Características Principales

  • Autenticación OAuth2 con client_id y client_secret
  • Creación de transacciones con un solo endpoint
  • Webhooks en tiempo real para notificaciones
  • Soporte para USDT y USDC
  • Documentación completa con ejemplos
  • Respuestas JSON estandarizadas

Autenticación

Para usar la API REST, necesitas autenticarte usando tus credenciales de cliente. Estas credenciales se obtienen al crear una cuenta de comerciante en nuestro sistema.

Ejemplo de Autenticación

// Autenticación con la API
$ch = curl_init('http://pay.buyesia.com/merchant/api/verify');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'client_id' => 'tu_client_id', // Obtén esto desde tu panel de comerciante
    'client_secret' => 'tu_client_secret' // Obtén esto desde tu panel de comerciante
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
$token = json_decode($response)->data->access_token;
Parámetro Descripción Obligatorio
client_id ID de cliente obtenido del panel de comerciante ✓
client_secret Secreto de cliente obtenido del panel de comerciante ✓

Transacciones

Para crear una nueva transacción, envía una solicitud POST con los detalles del pago.

Crear Transacción

// Crear una nueva transacción
$ch = curl_init('http://pay.buyesia.com/merchant/api/transaction-info');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'amount' => 100.00,
    'currency' => 'USDT',
    'successUrl' => 'https://tu-sitio-web.com/success',
    'cancelUrl' => 'https://tu-sitio-web.com/cancel',
    'order_no' => 'ORD-12345',
    'item_name' => 'Descripción del Producto'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
$transaction = json_decode($response);

// Redirigir al usuario a la página de pago
header('Location: ' . $transaction->data->approvedUrl);
Campo Descripción Obligatorio
amount Monto de la transacción ✓
currency Código de moneda (USDT o USDC) ✓
successUrl URL de redirección en caso de éxito ✓
cancelUrl URL de redirección en caso de cancelación ✓
order_no Número de orden único ✓
item_name Descripción del producto o servicio ✓
webhook_url URL para recibir notificaciones webhook ✗
metadata Datos adicionales en formato JSON ✗

Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real sobre eventos importantes en tu cuenta.

Configuración del Webhook

// Estructura del webhook recibido
{
    "event": "payment.success",
    "payload": {
        "transaction_id": "uuid-de-la-transaccion",
        "order_no": "ORD-12345",
        "item_name": "Nombre del producto",
        "amount": 1.00,
        "currency": "USDT",
        "status": "success",
        "timestamp": "2024-03-23T12:34:56Z"
    },
    "timestamp": 1234567890
}

// Headers del webhook
X-Webhook-Signature: [firma-hmac-sha256]
Content-Type: application/json

// Validación del webhook
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$payload = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $payload, $client_secret);

if (hash_equals($signature, $expectedSignature)) {
    $data = json_decode($payload, true);
    // Procesar el evento
}

Eventos Disponibles

  • payment.success - Pago completado exitosamente
  • payment.failed - Pago fallido
  • payment.refunded - Pago reembolsado

Ejemplos

Aquí hay un ejemplo completo de integración usando PHP.

Ejemplo Completo de Integración

// Configuración inicial
$apiUrl = 'http://pay.buyesia.com';
$clientId = 'tu_client_id'; // Obtén esto desde tu panel de comerciante
$clientSecret = 'tu_client_secret'; // Obtén esto desde tu panel de comerciante

// 1. Autenticación
$ch = curl_init($apiUrl . '/merchant/api/verify');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'client_id' => $clientId,
    'client_secret' => $clientSecret
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
$token = json_decode($response)->data->access_token;

// 2. Crear transacción
$ch = curl_init($apiUrl . '/merchant/api/transaction-info');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'amount' => 100.00,
    'currency' => 'USDT',
    'successUrl' => 'https://tu-sitio-web.com/success',
    'cancelUrl' => 'https://tu-sitio-web.com/cancel',
    'order_no' => 'ORD-12345',
    'item_name' => 'Descripción del Producto',
    'webhook_url' => 'https://tu-sitio-web.com/webhook',
    'metadata' => [
        'customer_id' => '12345',
        'invoice_id' => 'INV-001'
    ]
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
$transaction = json_decode($response);

// 3. Redirigir al usuario a la página de pago
header('Location: ' . $transaction->data->approvedUrl);

Seguridad

Aspectos importantes a considerar en la implementación:

Consideraciones de Seguridad

  • Siempre verifica la firma HMAC-SHA256 antes de procesar el webhook
  • Usa hash_equals() para comparar firmas de forma segura
  • Procesa los webhooks de forma asíncrona para evitar timeouts
  • Implementa reintentos en caso de fallos de entrega
  • Mantén un registro de los webhooks recibidos y procesados
  • Verifica el timestamp para evitar ataques de replay
  • Usa HTTPS para todas las comunicaciones

Manejo de Errores

// Ejemplo de manejo de errores
try {
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    if ($httpCode !== 200) {
        throw new Exception('Error en la solicitud: ' . $httpCode);
    }
    
    $data = json_decode($response);
    if (!$data || !isset($data->status) || $data->status !== 'success') {
        throw new Exception('Error en la respuesta: ' . ($data->message ?? 'Error desconocido'));
    }
} catch (Exception $e) {
    // Manejar el error apropiadamente
    error_log($e->getMessage());
    // Mostrar mensaje al usuario
    echo 'Ha ocurrido un error: ' . $e->getMessage();
}

Implementación

Sigue estos pasos para implementar la API REST en tu aplicación:

1

Crea una cuenta de comerciante

Regístrate en nuestro sistema y completa la verificación de tu cuenta de comerciante.

2

Obtén tus credenciales

Desde el panel de comerciante, obtén tu client_id y client_secret para la autenticación.

3

Implementa la autenticación

Usa el endpoint de autenticación para obtener tu token de acceso.

4

Crea transacciones

Implementa el endpoint de creación de transacciones en tu aplicación.

5

Configura webhooks

Configura los webhooks para recibir notificaciones en tiempo real.

6

Prueba la integración

Realiza pruebas completas con transacciones de prueba antes de ir a producción.

Recomendaciones

  • Guarda tus credenciales de forma segura
  • Implementa manejo de errores adecuado
  • Verifica siempre las respuestas de la API
  • Usa HTTPS para todas las comunicaciones
  • Siempre valida la firma del webhook usando tu client_secret
  • Procesa los webhooks de forma asíncrona para evitar timeouts
  • Implementa reintentos en caso de fallos de entrega
  • Mantén un registro de los webhooks recibidos

La billetera digital más confiable para venezolanos. Maneja tus finanzas con seguridad y facilidad usando criptomonedas estables.

Descarga nuestra app
Productos
  • Billetera Digital
  • Pasarela de Pagos
  • Pagos con QR
  • Envíos de Dinero
Soluciones
Recursos
Legal