Yappy Comercial

https://yappy-docs.vercel.app
Admin
Yappy Comercial permite integrar de forma segura métodos de cobro como el Botón de Pago para...
Tokens:30,033
Snippets:307
Trust Score:7.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Request Body Example

Source: https://yappy-docs.vercel.app/boton-pago/api-payment-wc

Example JSON payload for the /payments/payment-wc request. Ensure all monetary values are formatted as strings with two decimal places.

```json
{
  "merchantId": "5c2d13e5-537f-43f1-b1d0-d90d8fdaf8be",
  "orderId": "ORD12345",
  "domain": "https://www.tudominio.com",
  "paymentDate": 1777301827,
  "aliasYappy": "60021001",
  "ipnUrl": "https://www.tudominio.com/api/yappy/ipn",
  "shipping": "0.00",
  "discount": "0.00",
  "taxes": "0.35",
  "subtotal": "5.00",
  "total": "5.35"
}
```

--------------------------------

### Response Example

Source: https://yappy-docs.vercel.app/integraciones-yappy/api-history

Successful response containing paginated transaction data.

```json
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "pagination": {
      "limit": 10,
      "token": "BH/ytDLG1hzQ9xTx...",
      "end_date": "2026-06-15",
      "start_date": "2026-06-01",
      "has_next_page": false
    },
    "transactions": [
      {
        "id": "FCIZK-90454086",
        "number": "MOCK-g80ijzik",
        "type": "TXN-ECOM",
        "status": "COMPLETED",
        "description": "Por pedido: xJoK02cTOEUI",
        "role": "CREDIT",
        "category": "INTRABANK",
        "fee": {
          "currency": "USD",
          "amount": 0.16
        },
        "charge": {
          "currency": "USD",
          "tax": 0,
          "tip": 0,
          "amount": 10.11,
          "partial_amount": 10.11
        },
        "debitor": {
          "alias": "+50768994657",
          "complete_name": "Kallie Keeling",
          "alias_type": "P",
          "bank_name": "Banco General"
        },
        "creditor": {
          "alias": "Sitio web",
          "complete_name": "Mi Comercio S.A.",
          "alias_type": "C",
          "bank_name": "Banco General"
        },
        "cut_off_date": "2026-06-10",
        "payment_date": "2026-06-10T14:31:11.173Z",
        "bill_description": "",
        "registration_date": "2026-06-10T14:31:10.000Z"
      }
    ]
  }
}
```

--------------------------------

### Response Example

Source: https://yappy-docs.vercel.app/boton-pago/api-validate

The expected JSON response containing the session token and epoch time.

```json
{
  "status": {
    "code": "0000",
    "description": "Correct execution"
  },
  "body": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
    "epochTime": 1777301827
  }
}
```

--------------------------------

### Response 200 OK Example

Source: https://yappy-docs.vercel.app/boton-pago/api-payment-wc

Successful response structure containing the transaction ID and token.

```json
{
  "status": {
    "code": "0000",
    "description": "Correct execution"
  },
  "body": {
    "transactionId": "MRALB-83409803",
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "documentName": "transactions"
  }
}
```

--------------------------------

### Response structure for collection methods

Source: https://yappy-docs.vercel.app/integraciones-yappy/api-collection-method

Example of a successful 200 OK response containing the list of configured collection points and their associated details.

```json
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "collections": [
      {
        "alias": "techgeeks",
        "type": "Directorio"
      },
      {
        "alias": "Ventas en sitio",
        "type": "Punto Yappy"
      },
      {
        "alias": "Sucursal Multiplaza",
        "type": "Integración Yappy",
        "details": [
          { "id": "provided_group_id", "value": "smultiplaza" },
          { "id": "deviceId", "value": "smultiplaza-01" },
          { "id": "deviceId", "value": "smultiplaza-02" }
        ]
      },
      {
        "alias": "Sitio web",
        "type": "Boton de Pago",
        "details": [
          { "id": "url", "value": "https://www.micomercio.com" }
        ]
      }
    ]
  }
}
```

--------------------------------

### Request Body Example

Source: https://yappy-docs.vercel.app/boton-pago/api-validate

The JSON structure required for the POST request to validate the merchant.

```json
{
  "merchantId": "5c2d13e5-537f-43f1-b1d0-d90d8fdaf8be",
  "urlDomain": "https://www.tudominio.com"
}
```

--------------------------------

### Request Body Examples

Source: https://yappy-docs.vercel.app/integraciones-yappy/api-history

JSON payloads for requesting transaction history, either without filters or with a specific collection point filter.

```json
{
  "body": {
    "pagination": {
      "start_date": "2026-06-01",
      "end_date":   "2026-06-15",
      "limit": 10
    }
  }
}
```

```json
{
  "body": {
    "pagination": {
      "start_date": "2026-06-01",
      "end_date":   "2026-06-15",
      "limit": 10
    },
    "filter": [
      {
        "id": "COLLECTION_ALIAS",
        "value": "Sitio web"
      }
    ]
  }
}
```

--------------------------------

### Request collection methods

Source: https://yappy-docs.vercel.app/integraciones-yappy/api-collection-method

Perform a GET request to retrieve the list of collection methods. No body or parameters are required.

```http
GET https://api-integration-business-uat.yappycloud.com/v1/collection-method
```

--------------------------------

### GET /api/yappy/ipn

Source: https://yappy-docs.vercel.app/boton-pago/ipn

Endpoint que el backend debe exponer para recibir notificaciones de estado de transacciones desde Yappy.

```APIDOC
## GET /api/yappy/ipn

### Description
Endpoint expuesto por el comercio para recibir notificaciones instantáneas (IPN) sobre el estado de una orden. Yappy invoca este endpoint mediante una solicitud GET con los detalles de la transacción como parámetros de consulta.

### Method
GET

### Parameters
#### Query Parameters
- **orderId** (string) - Required - El orderId enviado al crear la orden.
- **hash** (string) - Required - Firma HMAC-SHA256 para validar la integridad de la notificación.
- **status** (string) - Required - Estado final de la transacción: 'E' (Ejecutado), 'C' (Cancelado), o 'X' (Expirado).
- **domain** (string) - Required - Dominio registrado en Yappy Comercial WEB.
- **confirmationNumber** (string) - Required - ID de la transacción del lado de Yappy para conciliación.

### Request Example
GET https://www.tudominio.com/api/yappy/ipn?orderId=ORD12345&hash=a3c1f8...e9d4&status=E&domain=https://www.tudominio.com&confirmationNumber=8f3e2c91-...

### Response
#### Success Response (200)
- El servidor debe responder con HTTP 200 en menos de 5 segundos para confirmar la recepción de la notificación.
```

--------------------------------

### GET /session/logout

Source: https://yappy-docs.vercel.app/integraciones-yappy/auth-logout

Closes an active work session previously opened with /session/login. This endpoint uses the GET method and does not require a request body.

```APIDOC
## GET /session/logout

### Description
Closes an active work session previously opened with /session/login. Note that this endpoint uses the GET method.

### Method
GET

### Endpoint
https://api-integration-business-uat.yappycloud.com/v1/session/logout

### Request Example
GET https://api-integration-business-uat.yappycloud.com/v1/session/logout

### Response
#### Success Response (200)
- **status** (object) - Contains the execution code and description.

#### Response Example
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  }
}
```

--------------------------------

### POST /qr/generate/DYN

Source: https://yappy-docs.vercel.app/yappy-en-caja/flujo-qr-dinamico

Genera un código QR dinámico para una transacción específica.

```APIDOC
## POST /qr/generate/DYN

### Description
Genera un QR dinámico basado en el monto del cobro. Retorna un transactionId y un hash necesario para la renderización visual del código.

### Method
POST

### Endpoint
/qr/generate/DYN
```

--------------------------------

### GET /session/logout

Source: https://yappy-docs.vercel.app/integraciones-yappy/overview

Terminates the currently active session.

```APIDOC
## GET /session/logout

### Description
Closes the active session.

### Method
GET

### Endpoint
/session/logout
```

--------------------------------

### GET /collection-method

Source: https://yappy-docs.vercel.app/integraciones-yappy/api-collection-method

Retrieves all collection points configured for the authenticated merchant.

```APIDOC
## GET /collection-method

### Description
Returns all collection points configured in Yappy Comercial for the authenticated merchant, along with their type and specific details. This is useful for obtaining exact names for filtering in `/movement/history` and auditing active collection methods.

### Method
GET

### Endpoint
https://api-integration-business-uat.yappycloud.com/v1/collection-method

### Response
#### Success Response (200)
- **status** (object) - Status code and description.
- **body.collections** (array) - List of configured collection points.
- **body.collections[].alias** (string) - Name of the collection point.
- **body.collections[].type** (string) - Type of collection point.
- **body.collections[].details** (array, optional) - Specific details based on type.

#### Response Example
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "collections": [
      {
        "alias": "Sucursal Multiplaza",
        "type": "Integración Yappy",
        "details": [
          { "id": "provided_group_id", "value": "smultiplaza" },
          { "id": "deviceId", "value": "smultiplaza-01" }
        ]
      }
    ]
  }
}
```

--------------------------------

### Importar el Web Component desde el CDN

Source: https://yappy-docs.vercel.app/boton-pago/web-component

Incluye el script del componente en tu HTML. Utiliza la URL de UAT para pruebas o la de producción para entornos reales.

```html
<script type="module" src="https://bt-cdn-uat.yappycloud.com/v1/cdn/web-component-btn-yappy.js"></script>
```

```html
<script type="module" src="https://bt-cdn.yappy.cloud/v1/cdn/web-component-btn-yappy.js"></script>
```

--------------------------------

### Implementar la lógica de integración

Source: https://yappy-docs.vercel.app/boton-pago/web-component

Escucha los eventos del componente para gestionar el flujo de pago, incluyendo la creación de la orden en el backend y la ejecución del método eventPayment.

```javascript
window.addEventListener("load", () => {
  const btnYappy = document.querySelector("btn-yappy");

  btnYappy.addEventListener("eventSuccess", (event) => {
    console.log("Transacción ejecutada: ", event.detail);
  });

  btnYappy.addEventListener("eventError", (event) => {
    console.log("Transacción fallida: ", event.detail);
  });

  btnYappy.addEventListener("eventClick", async () => {
    try {
      const response = await fetch('/api/crear-orden', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' }
      });
      const result = await response.json();
      if (result?.body?.token && result?.body?.documentName && result?.body?.transactionId) {
        btnYappy.eventPayment({
          transactionId: result.body.transactionId,
          documentName: result.body.documentName,
          token: result.body.token
        });
      }
    } catch (error) {
      console.error('Error:', error);
    }
  });
});
```

--------------------------------

### POST /qr/generate/{qr_type}

Source: https://yappy-docs.vercel.app/yappy-en-caja/api-qr-generate

Crea una nueva transacción y genera la información necesaria para mostrar (DYN) o asociar (HYB) el código QR.

```APIDOC
## POST /qr/generate/{qr_type}

### Description
Crea una nueva transacción y genera la información necesaria para mostrar (DYN) o asociar (HYB) el código QR.

### Method
POST

### Endpoint
/qr/generate/{qr_type}

### Parameters
#### Path Parameters
- **qr_type** (string) - Required - Tipo de QR: 'DYN' (dinámico) o 'HYB' (híbrido).

#### Request Body
- **body.charge_amount.sub_total** (number) - Required - Subtotal de la venta.
- **body.charge_amount.tax** (number) - Required - Impuesto (ITBMS).
- **body.charge_amount.tip** (number) - Required - Propina. Default: 0.
- **body.charge_amount.discount** (number) - Required - Descuento. Default: 0.
- **body.charge_amount.total** (number) - Required - Total a cobrar. Debe ser igual a sub_total + tax + tip - discount.
- **body.order_id** (string) - Optional - Identificador interno del comercio asociado a la orden (máx 15 caracteres).
- **body.description** (string) - Optional - Descripción de la venta (máx 64 caracteres).

### Request Example
{
  "body": {
    "charge_amount": {
      "sub_total": 200.52,
      "tax": 2.21,
      "tip": 0,
      "discount": 0,
      "total": 202.73
    },
    "order_id": "ORD-2026-00125",
    "description": "Almuerzo mesa 5"
  }
}

### Response
#### Success Response (200)
- **status.code** (string) - Código de estado de la operación.
- **status.description** (string) - Descripción del resultado.
- **body.date** (string) - Fecha de la transacción.
- **body.transactionId** (string) - Identificador de la transacción.
- **body.hash** (string) - Cadena alfanumérica para renderizar el QR (solo para DYN).

#### Response Example
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "date": "2026-05-15T08:15:32.500",
    "transactionId": "ORJBL-14890537",
    "hash": "z9y8x7w6v5u4t3s2r1q0p9o8"
  }
}
```

--------------------------------

### Implementación de generación de código

Source: https://yappy-docs.vercel.app/integraciones-yappy/auth-login

Ejemplos de cómo generar el hash dinámico en diferentes lenguajes de programación.

```javascript
const crypto = require('crypto');

function generarCode(apiKey, seed) {
  const fecha = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
  const mensaje = apiKey + fecha;
  return crypto.createHmac('sha256', seed).update(mensaje).digest('hex');
}
```

```python
import hmac, hashlib
from datetime import date

def generar_code(api_key: str, seed: str) -> str:
    fecha = date.today().isoformat()          # YYYY-MM-DD
    mensaje = (api_key + fecha).encode('utf-8')
    return hmac.new(seed.encode('utf-8'), mensaje, hashlib.sha256).hexdigest()
```

```php
function generarCode(string $apiKey, string $seed): string {
    $fecha   = date('Y-m-d');
    $mensaje = $apiKey . $fecha;
    return hash_hmac('sha256', $mensaje, $seed);
}
```

--------------------------------

### Validate Merchant API Calls

Source: https://yappy-docs.vercel.app/boton-pago/api-validate

Examples of how to call the validation endpoint using various programming languages.

```curl
curl -X POST https://api-comecom-uat.yappycloud.com/payments/validate/merchant \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "5c2d13e5-537f-43f1-b1d0-d90d8fdaf8be",
    "urlDomain": "https://www.tudominio.com"
  }'
```

```javascript
const response = await fetch("https://api-comecom-uat.yappycloud.com/payments/validate/merchant", {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    merchantId: process.env.YAPPY_MERCHANT_ID,
    urlDomain: 'https://www.tudominio.com'
  })
});

const { body } = await response.json();
const { token, epochTime } = body;
```

```python
import os, requests

resp = requests.post(
    "https://api-comecom-uat.yappycloud.com/payments/validate/merchant",
    headers={"Content-Type": "application/json"},
    json={
        "merchantId": os.environ["YAPPY_MERCHANT_ID"],
        "urlDomain": "https://www.tudominio.com",
    },
)
data = resp.json()["body"]
token, epoch_time = data["token"], data["epochTime"]
```

```php
<?php
$ch = curl_init("https://api-comecom-uat.yappycloud.com/payments/validate/merchant");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "merchantId" => getenv("YAPPY_MERCHANT_ID"),
  "urlDomain"  => "https://www.tudominio.com"
]));

$resp      = json_decode(curl_exec($ch), true);
$token     = $resp["body"]["token"];
$epochTime = $resp["body"]["epochTime"];
```

--------------------------------

### GET /transaction/{transactionId}

Source: https://yappy-docs.vercel.app/yappy-en-caja/flujo-qr-dinamico

Consulta el estado actual de una transacción mediante polling.

```APIDOC
## GET /transaction/{transactionId}

### Description
Consulta el estado de la transacción. Se recomienda realizar polling cada 2-5 segundos hasta obtener un estado final (COMPLETED o CANCELLED).

### Method
GET

### Endpoint
/transaction/{transactionId}

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - Identificador único de la transacción.
```

--------------------------------

### Configurar estilos del botón

Source: https://yappy-docs.vercel.app/boton-pago/web-component

Utiliza los atributos theme y rounded para personalizar la apariencia visual del componente.

```html
<btn-yappy rounded="true" theme="light"></btn-yappy>
```

--------------------------------

### Logout Request Endpoint

Source: https://yappy-docs.vercel.app/integraciones-yappy/auth-logout

The logout operation requires a GET request to the specified URL without a request body.

```http
GET https://api-integration-business-uat.yappycloud.com/v1/session/logout
```

--------------------------------

### POST /session/device

Source: https://yappy-docs.vercel.app/yappy-en-caja/flujo-qr-dinamico

Inicia una sesión de caja utilizando el identificador del dispositivo.

```APIDOC
## POST /session/device

### Description
Abre una sesión de caja para iniciar el proceso de cobro. Se debe guardar el token devuelto para autenticar llamadas posteriores.

### Method
POST

### Endpoint
/session/device
```

--------------------------------

### Ejemplos de implementación para abrir sesión

Source: https://yappy-docs.vercel.app/yappy-en-caja/api-session-open

Implementaciones del endpoint de apertura de sesión en diferentes lenguajes de programación.

```bash
curl -X POST "$YAPPY_BASE_URL/session/device" \
  -H "api-key: $YAPPY_API_KEY" \
  -H "secret-key: $YAPPY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "device": { "id": "sanfrancisco-01", "name": "Caja-01", "user": "CAJERO-001" },
      "group_id": "sanfrancisco"
    }
  }'
```

```javascript
const resp = await fetch(`${process.env.YAPPY_BASE_URL}/session/device`, {
  method: "POST",
  headers: {
    "api-key": process.env.YAPPY_API_KEY,
    "secret-key": process.env.YAPPY_SECRET_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    body: {
      device: { id: "sanfrancisco-01", name: "Caja-01", user: "CAJERO-001" },
      group_id: "sanfrancisco"
    }
  })
});
const { body } = await resp.json();
const sessionToken = body.token;
```

```python
import os, requests

resp = requests.post(
    f"{os.environ['YAPPY_BASE_URL']}/session/device",
    headers={
        "api-key": os.environ["YAPPY_API_KEY"],
        "secret-key": os.environ["YAPPY_SECRET_KEY"],
        "Content-Type": "application/json"
    },
    json={
        "body": {
            "device": {"id": "sanfrancisco-01", "name": "Caja-01", "user": "CAJERO-001"},
            "group_id": "sanfrancisco"
        }
    }
)
session_token = resp.json()["body"]["token"]
```

```php
<?php
$ch = curl_init(getenv("YAPPY_BASE_URL") . "/session/device");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "api-key: " . getenv("YAPPY_API_KEY"),
  "secret-key: " . getenv("YAPPY_SECRET_KEY"),
  "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "body" => [
    "device" => ["id" => "sanfrancisco-01", "name" => "Caja-01", "user" => "CAJERO-001"],
    "group_id" => "sanfrancisco"
  ]
]));
$resp = json_decode(curl_exec($ch), true);
$sessionToken = $resp["body"]["token"];
```

--------------------------------

### GET /transaction/:id

Source: https://yappy-docs.vercel.app/yappy-en-caja/estados-transaccion

Consulta el estado actual de una transacción específica mediante su identificador.

```APIDOC
## GET /transaction/:id

### Description
Obtiene el estado actual de una transacción específica.

### Method
GET

### Endpoint
/transaction/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Identificador único de la transacción.

### Response
#### Success Response (200)
- **status** (string) - El estado de la transacción. Valores posibles: PENDING, COMPLETED, CANCELLED, REVERSED, FAILED.
```

--------------------------------

### POST /session/device

Source: https://yappy-docs.vercel.app/yappy-en-caja/token-sesion

Inicia una nueva sesión de caja y retorna un token con una duración de 12 horas.

```APIDOC
## POST /session/device

### Description
Inicia una nueva sesión para la caja, retornando un token necesario para autenticar las operaciones posteriores.

### Method
POST

### Endpoint
/session/device
```

--------------------------------

### POST /session/device

Source: https://yappy-docs.vercel.app/yappy-en-caja/api-session-open

Inicia una sesión asociada a una unidad de cobro. Devuelve el token que se utilizará en todas las llamadas siguientes.

```APIDOC
## POST /session/device

### Description
Inicia una sesión asociada a una unidad de cobro. Devuelve el token que usarás en todas las llamadas siguientes.

### Method
POST

### Endpoint
/session/device

### Headers
- **api-key** (string) - Required - Tu API Key
- **secret-key** (string) - Required - Tu Clave Secreta
- **Content-Type** (string) - Required - application/json

### Request Body
- **body.device.id** (string) - Required - Nombre de la unidad de cobro (ej. sanfrancisco-01)
- **body.device.name** (string) - Optional - Nombre referencial de la caja.
- **body.device.user** (string) - Optional - Usuario referencial del cajero.
- **body.group_id** (string) - Required - ID del grupo (ej. sanfrancisco)

### Request Example
{
  "body": {
    "device": {
      "id": "sanfrancisco-01",
      "name": "Caja-01",
      "user": "CAJERO-001"
    },
    "group_id": "sanfrancisco"
  }
}

### Response
#### Success Response (200)
- **status.code** (string) - Código de estado de la operación
- **status.description** (string) - Descripción del resultado
- **body.status** (string) - Estado de la sesión (ej. OPEN)
- **body.opened_date** (string) - Fecha de apertura de la sesión
- **body.token** (string) - Token de sesión generado

#### Response Example
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "status": "OPEN",
    "opened_date": "2026-05-15T08:00:00.000",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

--------------------------------

### POST /session/login

Source: https://yappy-docs.vercel.app/integraciones-yappy/overview

Authenticates the merchant and initiates a session to obtain a JWT token.

```APIDOC
## POST /session/login

### Description
Opens a session and returns a JWT token required for subsequent API requests.

### Method
POST

### Endpoint
/session/login
```

--------------------------------

### Ejemplo de llamada IPN

Source: https://yappy-docs.vercel.app/boton-pago/ipn

Representación de la estructura de la solicitud GET que Yappy realiza a tu endpoint configurado.

```http
GET https://www.tudominio.com/api/yappy/ipn
  ?orderId=ORD12345
  &hash=a3c1f8...e9d4
  &status=E
  &domain=https://www.tudominio.com
  &confirmationNumber=8f3e2c91-...
```

--------------------------------

### DELETE /session/device

Source: https://yappy-docs.vercel.app/yappy-en-caja/token-sesion

Finaliza la sesión activa de la caja y retorna el resumen de las operaciones realizadas.

```APIDOC
## DELETE /session/device

### Description
Finaliza la vigencia del token de sesión actual y devuelve un resumen de las operaciones ejecutadas durante el período activo.

### Method
DELETE

### Endpoint
/session/device
```

--------------------------------

### GET /movement/{id}

Source: https://yappy-docs.vercel.app/integraciones-yappy/api-movement

Retrieves the complete details of a transaction based on its unique ID. This is useful for verifying the status of a specific transaction without fetching the entire history.

```APIDOC
## GET /movement/{id}

### Description
Devuelve el detalle completo de una transacción a partir de su ID único. Útil cuando necesitas verificar el estado actual de una transacción específica sin descargar todo el historial.

### Method
GET

### Endpoint
https://api-integration-business-uat.yappycloud.com/v1/movement/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - El ID único de la transacción con formato XXXXX-XXXXXXXX.

### Response
#### Success Response (200)
- **status** (object) - Objeto con el código y descripción de la respuesta.
- **body** (object) - Detalles de la transacción incluyendo id, number, type, status, description, role, category, fee, charge, debitor, y creditor.

#### Response Example
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "id": "ASOWE-45283003",
    "number": "MOCK-jamihs05",
    "type": "TXN-ECOM",
    "status": "REVERSED",
    "description": "Por pedido: xJoK02cTOEUI",
    "role": "CREDIT",
    "category": "INTRABANK",
    "fee": {
      "currency": "USD",
      "amount": 0.16
    },
    "charge": {
      "currency": "USD",
      "tax": 0,
      "tip": 0,
      "amount": 10.11,
      "partial_amount": 10.11
    },
    "debitor": {
      "alias": "+50768994657",
      "complete_name": "Kallie Keeling",
      "alias_type": "P",
      "bank_name": "Banco General"
    },
    "creditor": {
      "alias": "Sitio web",
      "complete_name": "Mi Comercio S.A."
    }
  }
}
```

--------------------------------

### Web Component Integration

Source: https://yappy-docs.vercel.app/boton-pago/web-component

How to include the Yappy Web Component via CDN and insert it into the DOM.

```APIDOC
## Web Component Installation

### CDN Import
Include the following script in your HTML:
```html
<script type="module" src="https://bt-cdn.yappy.cloud/v1/cdn/web-component-btn-yappy.js"></script>
```

### Usage
Insert the custom element into your page:
```html
<btn-yappy theme="blue" rounded="true"></btn-yappy>
```

### Attributes
- **theme** (string) - Optional - Visual style: "blue", "darkBlue", "orange", "dark", "sky", "light".
- **rounded** (boolean) - Optional - Set to "true" for rounded corners.
```

--------------------------------

### GET /transaction/{transaction_id}

Source: https://yappy-docs.vercel.app/yappy-en-caja/api-transaction-status

Consulta el estado actual de una transacción específica para determinar si el pago ha sido completado o cancelado.

```APIDOC
## GET /transaction/{transaction_id}

### Description
Consulta el estado actual de una transacción. Es el endpoint utilizado para polling con el fin de detectar cuándo el cliente realiza el pago.

### Method
GET

### Endpoint
/transaction/{transaction_id}

### Parameters
#### Path Parameters
- **transaction_id** (string) - Required - El identificador único de la transacción.

### Response
#### Success Response (200)
- **status** (object) - Objeto con el código y descripción del resultado de la ejecución.
- **body** (object) - Contiene el campo 'status' con el estado actual de la transacción.

#### Response Example
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "status": "COMPLETED"
  }
}
```

--------------------------------

### Llamada de ejemplo con Fetch API

Source: https://yappy-docs.vercel.app/yappy-en-caja/api-qr-generate

Implementación en JavaScript utilizando fetch para realizar la solicitud al endpoint de generación de QR.

```javascript
const resp = await fetch(`${process.env.YAPPY_BASE_URL}/qr/generate/DYN`, {
  method: "POST",
  headers: {
    "api-key": process.env.YAPPY_API_KEY,
    "secret-key": process.env.YAPPY_SECRET_KEY,
    "authorization": sessionToken,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    body: {
      charge_amount: {
        sub_total: 200.52,
        tax: 2.21,
        tip: 0,
        discount: 0,
        total: 202.73
      },
      order_id: "ORD-2026-00125",
      description: "Almuerzo mesa 5"
    }
  })
});
const { body } = await resp.json();
const { transactionId, hash } = body;
// Usa `hash` para renderizar el QR en pantalla
```

--------------------------------

### Pagination Logic

Source: https://yappy-docs.vercel.app/integraciones-yappy/api-history

Explains the process of using pagination tokens to retrieve full transaction history.

```APIDOC
## Pagination Logic

### Description
To retrieve the full transaction history, use the `pagination.token` field provided in the response body. If `has_next_page` is true, use the returned `token` in the next request to fetch the subsequent page.

### Request Body
- **pagination.start_date** (string) - Required - Start date for the transaction range.
- **pagination.end_date** (string) - Required - End date for the transaction range.
- **pagination.limit** (integer) - Required - Number of records per page.
- **pagination.token** (string) - Optional - Token for the next page of results.

### Request Example
{
  "body": {
    "pagination": {
      "start_date": "2026-06-01",
      "end_date": "2026-06-15",
      "limit": 10,
      "token": "BH/ytDLG1hzQ9xTx..."
    }
  }
}

### Error Codes
- **YP-0001**: No transactions found for the specified range/filter.
- **YP-0039**: Alias count in filter exceeds the maximum of 25.
- **YP-0040**: Limit is outside the allowed range.
- **YP-0010**: One or more body fields have invalid values.
- **YP-0008**: Missing mandatory headers.
```

--------------------------------

### Web Component Events and Methods

Source: https://yappy-docs.vercel.app/boton-pago/web-component

Documentation for the events emitted by the component and the methods available for interaction.

```APIDOC
## Component Interface

### Events
- **eventClick**: Triggered when the user clicks the button. Use this to initiate order creation.
- **eventSuccess**: Triggered upon successful transaction. Details are available in `event.detail`.
- **eventError**: Triggered when a transaction fails. Details are available in `event.detail`.

### Methods
- **eventPayment({ transactionId, token, documentName })**: Invoked to process the payment after order creation.

### Properties
- **isYappyOnline** (boolean) - Returns true if the Yappy channel is available.
- **isButtonLoading** (boolean) - Set to true to display the loading state.
- **triggerModal** (boolean) - Controls the visibility of the transaction counter modal.
```

--------------------------------

### Ejemplo de cabeceras correctas

Source: https://yappy-docs.vercel.app/integraciones-yappy/troubleshooting

Marcador de posición para la configuración correcta de cabeceras HTTP.

```bash
# Correcto
```

--------------------------------

### Configuración de variables de entorno para Yappy

Source: https://yappy-docs.vercel.app/boton-pago/production

Ejemplos de configuración para los entornos de desarrollo (UAT) y producción, destacando el cambio de URLs base, CDN y credenciales.

```text
# Entorno UAT (desarrollo)
YAPPY_BASE_URL=https://api-comecom-uat.yappycloud.com
YAPPY_CDN_URL=https://bt-cdn-uat.yappycloud.com/v1/cdn/web-component-btn-yappy.js
YAPPY_MERCHANT_ID=5c2d13e5-537f-43f1-b1d0-d90d8fdaf8be
YAPPY_CLAVE_SECRETA=dGVzdGluZy1zZWNyZXQtdWF0LWJhc2U2NC1lbmNvZGVkLWhlcmU=
```

```text
# Entorno PRODUCTIVO
YAPPY_BASE_URL=https://apipagosbg.bgeneral.cloud
YAPPY_CDN_URL=https://bt-cdn.yappy.cloud/v1/cdn/web-component-btn-yappy.js
YAPPY_MERCHANT_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890   # NUEVO
YAPPY_CLAVE_SECRETA=cHJvZHVjdGlvbi1zZWNyZXQtYmFzZTY0LWVuY29kZWQtaGVyZQ==  # NUEVO
```

--------------------------------

### Flujo end-to-end con QR dinámico

Source: https://yappy-docs.vercel.app/yappy-en-caja/flujo-qr-dinamico

Bloque de código vacío que representa el inicio del flujo de integración.

```text

```

--------------------------------

### Cuerpo de la solicitud de Login

Source: https://yappy-docs.vercel.app/integraciones-yappy/auth-login

Estructura JSON requerida para el login, donde el campo code debe ser calculado dinámicamente.

```json
{
  "body": {
    "code": "f957f8b8f9664832e6051e3389864682624a8e2b9aaf4dd80fb2aaea7af58940"
  }
}
```

--------------------------------

### Implementación de polling para verificación de pago

Source: https://yappy-docs.vercel.app/yappy-en-caja/api-transaction-status

Función asíncrona que consulta periódicamente el estado de la transacción y maneja la expiración tras el tiempo límite definido.

```javascript
async function waitForPayment(transactionId, sessionToken, timeoutMs = 300_000) {
  const deadline = Date.now() + timeoutMs;
  const POLL_INTERVAL = 3000;

  while (Date.now() < deadline) {
    const resp = await fetch(
      `${process.env.YAPPY_BASE_URL}/transaction/${transactionId}`,
      {
        headers: {
          "api-key": process.env.YAPPY_API_KEY,
          "secret-key": process.env.YAPPY_SECRET_KEY,
          "authorization": sessionToken
        }
      }
    );
    const { body } = await resp.json();

    if (body.status === "COMPLETED") return "paid";
    if (body.status === "CANCELLED") return "cancelled";

    await new Promise(r => setTimeout(r, POLL_INTERVAL));
  }

  // 5 min pasaron sin pago: cancelar la transacción
  await cancelTransaction(transactionId, sessionToken);
  return "expired";
}
```

--------------------------------

### Insertar el botón en el DOM

Source: https://yappy-docs.vercel.app/boton-pago/web-component

Añade el elemento personalizado al HTML para renderizar el botón de pago.

```html
<btn-yappy theme="blue"></btn-yappy>
```

--------------------------------

### Ejemplo de respuesta exitosa 200 OK

Source: https://yappy-docs.vercel.app/yappy-en-caja/api-qr-generate

Respuesta esperada tras una generación exitosa, incluyendo el hash para QR dinámicos.

```json
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  },
  "body": {
    "date": "2026-05-15T08:15:32.500",
    "transactionId": "ORJBL-14890537",
    "hash": "z9y8x7w6v5u4t3s2r1q0p9o8"
  }
}
```

--------------------------------

### Respuestas de la API de anulación

Source: https://yappy-docs.vercel.app/integraciones-yappy/api-transaction-cancel

Ejemplos de respuestas JSON para diferentes escenarios de anulación.

```json
{
  "status": {
    "code": "YP-0000",
    "description": "Se ha realizado la ejecución del servicio correctamente"
  }
}
```

```json
{
  "status": {
    "code": "YP-0016",
    "description": "La transaccion que se intenta reversar posee un estado reversado. No se requieren acciones adicionales."
  }
}
```

```json
{
  "status": {
    "code": "YP-0014",
    "description": "Error, la reversa no puede ser procesada porque ya se liquido."
  }
}
```

```json
{
  "status": {
    "code": "YP-0015",
    "description": "La transaccion que se intenta reversar posee un estado fallido. No se requieren acciones adicionales."
  }
}
```
Tokens:
Raw