Developer

Resumen

La integración actual se apoya en tres endpoints públicos y un checkout web que se genera automáticamente desde la API.

1. Verifica credenciales

`POST /merchant/api/verify`

Recibe client_id y client_secret, valida el merchant y devuelve un access_token temporal.

2. Crea la orden

`POST /merchant/api/transaction-info`

Genera la referencia, el checkout_token y la approvedUrl lista para redirigir al comprador al checkout alojado.

3. Consulta currencies y escucha eventos

`payment.success`

Consulta las monedas disponibles cuando lo necesites y procesa confirmaciones firmadas por webhook usando el client_secret de tu merchant.

Inicio rápido

Este es el flujo mínimo recomendado para pasar de credenciales a checkout funcionando.

1

Obtén client_id y client_secret

Usa las credenciales del merchant express desde el panel correspondiente.

2

Solicita el access token

Haz un POST a /merchant/api/verify y conserva el token para la siguiente llamada.

3

Crea la transacción y redirige

Envía amount, currency y URLs de retorno; luego redirige al comprador al approvedUrl.

4

Valida webhooks

Procesa payment.success y payment.failed usando la firma X-Webhook-Signature sobre el body raw.

Autenticación

El endpoint de verificación devuelve un token de acceso con validez temporal. La llamada actual no usa OAuth formal; usa client_id y client_secret directamente.

POST https://pay.buyesia.com/merchant/api/verify

Devuelve status, message y data.access_token cuando las credenciales son válidas.

Campo	Tipo	Requerido	Descripción
`client_id`	string	Sí	Identificador del merchant app.
`client_secret`	string	Sí	Secreto del merchant app usado también para firmar webhooks.

Solicitud cURL

curl --request POST 'https://pay.buyesia.com/merchant/api/verify' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "tu_client_id",
    "client_secret": "tu_client_secret"
}'

Response JSON

{
    "status": "success",
    "message": "Client Verified",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.demo"
    }
}

Monedas disponibles

Este endpoint devuelve las monedas que tu checkout puede aceptar en este momento según los métodos activos del panel admin y la configuración real del merchant autenticado.

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

Úsalo para poblar selectores o validar qué currencies pueden enviarse a transaction-info. El comprador elegirá el método de pago dentro del checkout alojado.

Solicitud cURL

curl --request GET 'https://pay.buyesia.com/merchant/api/available-currencies' \
  --header 'Authorization: Bearer TU_ACCESS_TOKEN'

Crear transacción

Este endpoint genera la intención de pago, la referencia interna y la URL de checkout que consume el comprador.

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

Requiere Authorization: Bearer {access_token}. Envía solamente la currency y el checkout alojado mostrará las opciones activas compatibles con esa moneda.

Campo	Tipo	Requerido	Descripción
`amount`	number	Sí	Monto mayor a 0.
`currency`	string	Sí	Código de moneda soportado por tu checkout, por ejemplo USD, USDT o USDC. Puedes consultarlas previamente en /merchant/api/available-currencies.
`successUrl`	string	Sí	URL del merchant a la que se redirige cuando el pago concluye.
`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 destino para eventos de transaction.created, payment.success y transaction.failed.
`metadata`	object	No	Objeto libre que el backend conserva y reenvía en el webhook.

Solicitud cURL

curl --request POST 'https://pay.buyesia.com/merchant/api/transaction-info' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer TU_ACCESS_TOKEN' \
  --data '{
    "amount": 100,
    "currency": "USD",
    "successUrl": "https://merchant.example/success",
    "cancelUrl": "https://merchant.example/cancel",
    "order_no": "ORD-2026-1001",
    "item_name": "Suscripción Pro",
    "webhook_url": "https://merchant.example/webhooks/buyesia",
    "metadata": {
        "customer_id": "cus_128",
        "plan": "pro"
    }
}'

Response JSON

{
    "status": "success",
    "message": "Transaction Info Created Successfully!",
    "data": {
        "approvedUrl": "https://pay.buyesia.com/merchant/checkout/chk_demo_token_123",
        "checkout_token": "chk_demo_token_123",
        "grant_id": 18354021,
        "token": "Cj2mMNt5sE7P9dZrQa4K",
        "amount": "100.00",
        "currency": "USD",
        "order_no": "ORD-2026-1001",
        "item_name": "Suscripción Pro",
        "status": "pending",
        "payment_method": null,
        "metadata": {
            "customer_id": "cus_128",
            "plan": "pro"
        }
    }
}

Flujo de checkout

Una vez creada la transacción, redirige al comprador usando approvedUrl. El checkout alojado resolverá automáticamente los métodos disponibles según la moneda elegida y los métodos activos del merchant.

Patrón actual del checkout web: https://pay.buyesia.com/merchant/checkout/{checkout_token}

Campo recomendado

`approvedUrl`

Es la URL principal que debes usar para redirigir al usuario en web.

Selección del comprador

Métodos dinámicos en checkout

La pantalla de checkout mostrará únicamente las opciones activas y compatibles con la currency enviada en la orden.

Webhooks

Los webhooks salen firmados con HMAC SHA-256 sobre el body JSON completo. La firma viaja en el header X-Webhook-Signature.

Header requerido

`X-Webhook-Signature`

Calculado con hash_hmac("sha256", raw_body, client_secret).

Eventos emitidos

`transaction.created`, `payment.success`, `transaction.failed`

Usa order_no y transaction_id para reconciliar tu pedido interno.

Payload real

{
    "event": "payment.success",
    "payload": {
        "transaction_id": "f8e4af91-9946-469f-b3cf-7b5b8a35d4e3",
        "order_no": "ORD-2026-1001",
        "item_name": "Suscripción Pro",
        "metadata": {
            "customer_id": "cus_128",
            "plan": "pro"
        },
        "amount": 100,
        "currency": "USD",
        "status": "success",
        "timestamp": "2026-03-29T09:45:18+00:00"
    },
    "timestamp": 1774777518
}

Validación PHP

<?php

$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 inválida']);
    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]);

Ejemplo PHP real

Este ejemplo sigue el contrato actual del backend: autentica, crea la transacción y redirige al checkout usando approvedUrl.

Integración completa

<?php

$baseUrl = 'https://pay.buyesia.com';
$clientId = 'tu_client_id';
$clientSecret = 'tu_client_secret';

function apiPost(string $url, array $payload, array $headers = []): array
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => array_merge([
            'Content-Type: application/json',
        ], $headers),
        CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
    ]);

    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($raw === false) {
        throw new RuntimeException(curl_error($ch));
    }

    curl_close($ch);

    return [
        'status_code' => $status,
        'body' => json_decode($raw, true),
    ];
}

// 1. Verificar credenciales y obtener access token
$auth = apiPost($baseUrl . '/merchant/api/verify', [
    'client_id' => $clientId,
    'client_secret' => $clientSecret,
]);

if (($auth['body']['status'] ?? null) !== 'success') {
    throw new RuntimeException($auth['body']['message'] ?? 'No se pudo autenticar');
}

$token = $auth['body']['data']['access_token'];

// 2. Crear la transacción
    $payment = apiPost(
    $baseUrl . '/merchant/api/transaction-info',
    [
        'amount' => 100.00,
        'currency' => 'USD',
        'successUrl' => 'https://merchant.example/success',
        'cancelUrl' => 'https://merchant.example/cancel',
        'order_no' => 'ORD-2026-1001',
        'item_name' => 'Suscripción Pro',
        'webhook_url' => 'https://merchant.example/webhooks/buyesia',
        'metadata' => [
            'customer_id' => 'cus_128',
            'plan' => 'pro',
        ],
    ],
    ['Authorization: Bearer ' . $token]
);

if (($payment['body']['status'] ?? null) !== 'success') {
    throw new RuntimeException($payment['body']['message'] ?? 'No se pudo crear la transacción');
}

// 3. Redirigir al checkout real devuelto por la API
$checkoutUrl = $payment['body']['data']['approvedUrl'];
header('Location: ' . $checkoutUrl);
exit;

Comportamiento del checkout

El integrador no necesita elegir el gateway manualmente. Buyesia Pay decide qué opciones mostrar según la moneda de la orden y los métodos activos configurados en el panel admin.

1

Consulta las monedas habilitadas

Usa /merchant/api/available-currencies para saber qué currencies están disponibles en tu checkout antes de crear la orden.

2

Crea la transacción con una moneda válida

Envía amount, currency, successUrl y cancelUrl. No necesitas indicar el método de pago en la solicitud normal del checkout.

3

Redirige a approvedUrl

El usuario verá dentro del checkout las opciones activas que coincidan con la moneda enviada y podrá completar el pago allí.

4

Escucha el webhook final

La confirmación de pago te llegará firmada por webhook. Usa order_no o transaction_id para reconciliar la orden en tu sistema.

Resumen

POST /merchant/api/verify

POST /merchant/api/transaction-info

payment.success

Inicio rápido

Obtén client_id y client_secret

Solicita el access token

Crea la transacción y redirige

Valida webhooks

Autenticación

Monedas disponibles

Crear transacción

Flujo de checkout

approvedUrl

Métodos dinámicos en checkout

Webhooks

X-Webhook-Signature

transaction.created, payment.success, transaction.failed

Ejemplo PHP real

Comportamiento del checkout

Consulta las monedas habilitadas

Crea la transacción con una moneda válida

Redirige a approvedUrl

Escucha el webhook final

Política de Cookies

`POST /merchant/api/verify`

`POST /merchant/api/transaction-info`

`payment.success`

`approvedUrl`

`X-Webhook-Signature`

`transaction.created`, `payment.success`, `transaction.failed`