Categoría por categoría
Cada ficha trae los productos, qué escribir en identifier, las
llamadas listas para copiar y lo que conviene imprimir en el recibo.
📱 Telefonía: recargas de celular
monto_libre
La venta más común y la más sencilla: el cliente dice el número y cuánto quiere recargar.
1CLARO · RD$30–2,000
2ALTICE · RD$30–2,000
3VIVA · RD$25–2,000
4DIGICEL (Haití) · RD$50–2,000
5NATCOM (Haití) · RD$50–2,000
Qué va en identifier
- Claro, Altice, Viva: 10 dígitos que empiezan por 809, 829 u 849. La API quita guiones, espacios y el
1 de delante: 809-555-1235 y 18095551235 valen.
- Digicel y Natcom son de Haití:
509 + 8 dígitos, por ejemplo 50946329825. Si escribe solo los 8 dígitos locales, la API pone el 509.
La venta (un solo paso)
curl -s -X POST "$API/v1/recargas" -H "$AUTH" \
-H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
-H "Content-Type: application/json" \
-d '{"service_id":1,"identifier":"8095551235","amount":100,"terminal_id":"CAJA-01"}'
Respuesta real · 201
{
"success": true,
"data": {
"transaction_id": 76672,
"status": "SUCCESS",
"xid": "RD-d1ce0d0620030ef62e4f9ee3",
"reference": "RD-d1ce0d0620030ef62e4f9ee3",
"auth_code": "813370",
"service": { "id": 1, "nombre": "CLARO" },
"identifier": "8095551235",
"amount": 100,
"currency": "DOP",
"message": "Operación procesada exitosamente.",
"processed_at": "2026-10-31T10:40:38-04:00",
"environment": "sandbox"
},
"message": "Recarga procesada exitosamente",
"request_id": "req_96df431c890d5b5a93c81451"
}
Errores que verá al principio
Monto fuera de rango:
{ "code": "VALIDATION_ERROR",
"message": "El monto máximo para este servicio es RD$2000.00.",
"details": { "amount": "mayor_al_maximo", "maximo": 2000 } }
Número incompleto (se rechaza antes de cobrar):
{ "code": "VALIDATION_ERROR",
"message": "El número debe tener 10 dígitos. Recibimos 8. Ejemplo válido: 8095551234.",
"details": { "identifier": "longitud_invalida",
"digitos_recibidos": 8, "digitos_esperados": 10 } }
El recibo
RECARGA.DO
Colmado La Esquina · CAJA-01
--------------------------------
Recarga CLARO
Número: 809-555-1235
Monto: RD$ 100.00
Autoriz.: 813370
Operación: 76672
31/10/2026 10:40
--------------------------------
Conserve este comprobante
El auth_code es lo que el cliente
le dará al operador si su recarga no llega.
¿Puedo consultar antes?
Sí, es opcional. POST /v1/consultas con un producto de monto libre le devuelve el rango
permitido, útil para validar en pantalla:
{ "flujo": "monto_libre", "requiere_seleccion": false, "opciones": [],
"monto": { "minimo": 30, "maximo": 2000 },
"mensaje": "Indique el monto a recargar." }
¿Y el postpago de Claro o Altice?
No es una recarga, es pagar una factura: CLARO POSTPAGO (6)
y ALTICE POSTPAGO (7) siguen el flujo de
facturas, con el número de contrato o cuenta como identifier.
📶 Paquetes de datos
paquetes
El cliente no elige un monto: elige un paquete. Y los paquetes
dependen del número: dos líneas Claro pueden tener ofertas distintas.
Por eso siempre se consulta primero.
50Claro Paquetes
51ALTICE Paquetes
52Viva Paquetes
53Digicel Paquetes (Haití)
identifier: el número de teléfono, con las mismas reglas que las recargas.
Paso 1 · Consultar qué paquetes tiene ese número
curl -s -X POST "$API/v1/consultas" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"service_id":50,"identifier":"8094964444"}'
Respuesta real · 200
{
"success": true,
"data": {
"servicio": { "id": 50, "nombre": "Claro Paquetes", "flujo": "paquetes" },
"identificador": "8094964444",
"flujo": "paquetes",
"origen_datos": "simulado",
"requiere_seleccion": true,
"opciones": [
{ "opcion_id": "CL-D30", "nombre": "Paquetito Diario 1GB", "precio": 30, "vigencia": "1 día", "datos": "1 GB", "minutos": 15, "sms": 15 },
{ "opcion_id": "CL-S150", "nombre": "Semanal 4GB + Redes", "precio": 150, "vigencia": "7 días", "datos": "4 GB", "minutos": 60, "sms": 60 },
{ "opcion_id": "CL-M400", "nombre": "Mensual 10GB", "precio": 400, "vigencia": "30 días", "datos": "10 GB", "minutos": 200, "sms": 200 },
{ "opcion_id": "CL-M700", "nombre": "Mensual Ilimitado Redes", "precio": 700, "vigencia": "30 días", "datos": "25 GB", "minutos": 500, "sms": 500 }
],
"monto": null,
"mensaje": "4 paquetes disponibles para este número."
}
}
Muestre la lista al cajero: nombre, precio, vigencia y
datos. Cuando el cliente elija, guarde su opcion_id.
Paso 2 · Vender el paquete elegido (sin amount)
curl -s -X POST "$API/v1/recargas" -H "$AUTH" \
-H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
-H "Content-Type: application/json" \
-d '{"service_id":50,"identifier":"8094964444","opcion_id":"CL-D30"}'
Respuesta real · 201
{
"success": true,
"data": {
"transaction_id": 76673,
"status": "SUCCESS",
"auth_code": "930813",
"service": { "id": 50, "nombre": "Claro Paquetes" },
"identifier": "8094964444",
"amount": 30,
"currency": "DOP",
"message": "Operación procesada exitosamente."
}
}
El amount de la respuesta es el precio real que se descontó de su saldo. Úselo
para cobrarle al cliente.
Si se olvida de consultar
Si envía amount en vez de opcion_id, no se cobra nada y la API le explica el camino:
{ "code": "VALIDATION_ERROR",
"message": "\"Claro Paquetes\" se vende por paquetes, no por monto libre. Consulte primero POST /v1/consultas para obtener los paquetes de ese número, y envíe el `opcion_id` elegido.",
"details": { "opcion_id": "requerido", "flujo": "paquetes", "consultar_opciones_en": "/v1/consultas" } }
Y si envía los dos, el amount tiene que coincidir con el precio del paquete; si no, se rechaza.
No guarde la lista de paquetes en su sistema
Cambia según el número y según el día. Consulte en cada venta. Si el paquete ya no existe
cuando cobra, la API responde opcion_id: "no_disponible" y basta con volver a consultar.
📺 Internet y TV
facturaspaquetes
Esta categoría mezcla dos flujos. Mire el flujo de cada servicio.
Los de factura se venden como en Luz por factura, y Wind Paquetes como en
Paquetes de datos. Ejemplo real de la consulta de Wind Paquetes:
curl -s -X POST "$API/v1/consultas" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"service_id":19,"identifier":"8094964444"}'
"opciones": [
{ "opcion_id": "WD-M500", "nombre": "Wind Internet Hogar 20GB", "precio": 500, "vigencia": "30 días", "datos": "20 GB" },
{ "opcion_id": "WD-M900", "nombre": "Wind Internet Hogar 50GB", "precio": 900, "vigencia": "30 días", "datos": "50 GB" }
]
El cliente compra energía por adelantado: elige el monto, como en una recarga.
Hay dos diferencias importantes: conviene confirmar el titular antes de cobrar,
y la respuesta trae un código que el cliente mete en su medidor.
22EDESUR PREPAGO · RD$50–1,500
30CEPM PREPAGO · RD$50–1,500
33ACTIVA PREPAGO · RD$50–1,500
identifier: el número de contrato o NIC (de 4 a 20 dígitos), el que aparece en la factura o el carnet del cliente.
Paso 1 (recomendado) · Confirmar a nombre de quién está el contrato
curl -s -X POST "$API/v1/consultas" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"service_id":22,"identifier":"7001234567"}'
{
"flujo": "monto_libre",
"titular": "ANA MERCEDES SANTOS",
"verificacion": "confirmado",
"requiere_seleccion": false,
"monto": { "minimo": 50, "maximo": 1500 },
"datos_adicionales": {
"contrato": "7001234567",
"medidor": "M-0f36d479",
"tarifa": "BTS1 - Residencial",
"total_recargado_mes": 200
},
"mensaje": "Titular confirmado. Indique el monto a recargar."
}
El cajero lee en voz alta: "¿Ana Mercedes Santos?". Si el cliente dice que sí, se
cobra. Así se evita el error más caro de esta categoría: cargarle la luz a otro contrato.
Paso 2 · Vender
curl -s -X POST "$API/v1/recargas" -H "$AUTH" \
-H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
-H "Content-Type: application/json" \
-d '{"service_id":22,"identifier":"7001234567","amount":500}'
Respuesta real · 201
{
"success": true,
"data": {
"transaction_id": 76675,
"status": "SUCCESS",
"auth_code": "830747",
"service": { "id": 22, "nombre": "EDESUR PREPAGO" },
"identifier": "7001234567",
"amount": 500,
"currency": "DOP",
"message": "Operación procesada exitosamente.",
"details": {
"contrato": "7001234567",
"token_recarga": "0747-3843-6730-3341-1667",
"medidor": "000006830747",
"tarifa": 16.47,
"energia_acreditada": 30.36,
"lote": "0"
}
}
}
Guarde e imprima el token_recarga en ese momento
Es el código que el cliente teclea en su medidor para recibir la energía. Sin él, pagó
y no tiene luz.
Solo viene en la respuesta de la venta. Ni
GET /v1/transacciones/{id} ni el recibo de la API lo repiten. Guárdelo en
su base de datos junto a la venta antes de hacer cualquier otra cosa.
El recibo
RECARGA.DO
--------------------------------
EDESUR PREPAGO
Contrato: 7001234567
Titular: ANA MERCEDES SANTOS
Monto: RD$ 500.00
Energía: 30.36 kWh
CÓDIGO PARA SU MEDIDOR:
0747-3843-6730-3341-1667
Autoriz.: 830747
Operación: 76675
--------------------------------
💡 Luz por factura (y cualquier factura)
facturas
El cliente viene a pagar lo que debe. El monto lo pone la distribuidora, no
usted. Esta ficha sirve de modelo para todas las facturas: agua, teléfono
postpago, internet, universidades, préstamos, impuestos.
9EDESUR
8EDENORTE
10EDEESTE
29CEB
27CEPM
Ojo con los nombres parecidos
EDESUR (9) se paga por factura; EDESUR PREPAGO
(22) es luz prepago. Son productos distintos: pregúntele
al cliente si tiene medidor prepago.
Paso 1 · Consultar qué debe ese contrato
curl -s -X POST "$API/v1/consultas" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"service_id":9,"identifier":"7001234567"}'
Respuesta real · 200 (recortada a la primera factura)
{
"success": true,
"data": {
"servicio": { "id": 9, "nombre": "EDESUR", "flujo": "facturas" },
"flujo": "facturas",
"titular": "ANA MERCEDES SANTOS",
"requiere_seleccion": true,
"opciones": [
{
"opcion_id": "F-202610-4567",
"nombre": "Factura F-202610-4567",
"descripcion": "Consumo del mes en curso",
"precio": 1676.76,
"periodo": "10/2026",
"vencimiento": "2026-10-25",
"acepta_pago": true,
"mora": null
}
],
"datos_adicionales": { "direccion": "CALLE PRINCIPAL #77, SANTO DOMINGO" },
"resumen": { "facturas_pendientes": 2, "total_adeudado": 3052.89 },
"sin_deuda": false,
"mensaje": "2 facturas pendientes."
}
}
Muestre al cajero el titular, la dirección y cada factura con su precio
y vencimiento, para que el cliente confirme que es su cuenta.
Paso 2 · Pagar la factura elegida
curl -s -X POST "$API/v1/recargas" -H "$AUTH" \
-H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
-H "Content-Type: application/json" \
-d '{"service_id":9,"identifier":"7001234567","opcion_id":"F-202610-4567"}'
Respuesta real · 201
{
"success": true,
"data": {
"transaction_id": 76674,
"status": "SUCCESS",
"auth_code": "686608",
"service": { "id": 9, "nombre": "EDESUR" },
"identifier": "7001234567",
"amount": 1676.76,
"currency": "DOP",
"message": "Operación procesada exitosamente."
}
}
Pago parcial (abonos)
Si el cliente no puede pagar la factura completa, agregue amount con lo que va a
abonar. Puede ser menos que la factura, nunca más:
-d '{"service_id":9,"identifier":"7001234567","opcion_id":"F-202610-4567","amount":1000}'
// Si pide más que la factura, no se cobra:
{ "code": "VALIDATION_ERROR",
"message": "Esa factura es de RD$1676.76. Puede pagar ese monto o uno menor (pago parcial), no RD$2000.00.",
"details": { "amount": "excede_factura", "monto_factura": 1676.76 } }
No todas las empresas aceptan abonos
Si la empresa que cobra no admite pagos parciales, la venta se rechaza y su saldo se libera
solo. Si no tiene claro que el cliente quiere abonar, no envíe amount:
se paga el total y no hay sorpresas.
Cuando el cliente no debe nada
La consulta responde 200 con sin_deuda: true y la lista vacía.
No es un error: muestre "Está al día" y no ofrezca cobrar.
{ "flujo": "facturas", "titular": "CARMEN ROSA JIMENEZ",
"requiere_seleccion": false, "opciones": [],
"resumen": { "facturas_pendientes": 0, "total_adeudado": 0 },
"sin_deuda": true,
"mensaje": "Este contrato está al día: no hay facturas pendientes." }
Si acepta_pago de una factura viene en false, avise al cajero: la
distribuidora podría rechazarla. Si la rechaza, su saldo se libera.
Todas las de agua se pagan por factura, exactamente como la luz.
13CAASD
11CORAASAN
15CORAAVEGA
14CORAAPLATA
23ASDN
identifier: el número de contrato o cuenta que aparece en la factura del agua.
curl -s -X POST "$API/v1/consultas" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"service_id":13,"identifier":"123456789"}'
{ "flujo": "facturas", "titular": "ROSA ELENA MARTINEZ",
"opciones": [ { "opcion_id": "F-202610-6789", "descripcion": "Consumo del mes en curso",
"precio": 2729.29, "vencimiento": "2026-10-25", "acepta_pago": true } ],
"resumen": { "facturas_pendientes": 2, "total_adeudado": 4358.49 } }
Y se paga con POST /v1/recargas enviando ese opcion_id, igual que en
Luz por factura.
🎲 Entretenimiento
monto_libre
Se recarga saldo a una cuenta: el cliente dice su número de cuenta y el monto.
Se vende igual que una recarga de celular.
curl -s -X POST "$API/v1/recargas" -H "$AUTH" \
-H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
-H "Content-Type: application/json" \
-d '{"service_id":32,"identifier":"123456789","amount":500}'
Montos altos, más cuidado
Algunos de estos productos admiten montos muy altos. Pida al cajero que confirme el número de
cuenta antes de cobrar: una recarga a la cuenta equivocada no siempre se puede anular. Revise
acepta_anulacion en GET /v1/servicios.
🏦 Financieros, gobierno y otros pagos
facturas
Préstamos, impuestos, multas, universidades y ventas por catálogo. Todos se
pagan por factura: se consulta lo que el cliente debe y se paga la opción elegida. Lo único
que cambia es qué dato pide cada uno.
Ejemplo real con la DGII:
curl -s -X POST "$API/v1/consultas" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"service_id":47,"identifier":"101234567"}'
{ "flujo": "facturas", "titular": "PEDRO ANTONIO GOMEZ",
"opciones": [ { "opcion_id": "F-202610-4567", "precio": 1173.73,
"vencimiento": "2026-10-25", "acepta_pago": true } ],
"resumen": { "facturas_pendientes": 2, "total_adeudado": 2546.88 } }
El pago es idéntico al de Luz por factura, incluido el pago parcial.
¿Por qué un préstamo o un impuesto es una "factura"?
Porque el monto lo fija quien cobra, no usted. Para la API eso es lo que define una factura,
sea de luz, de la universidad o de la DGII.
🚗 Seguros de vehículo
seguros
Es la categoría más larga de programar. Se habilita por comercio:
pídasela a Recarga.do. Con las credenciales públicas de prueba, la venta responde
403 FORBIDDEN («Este producto no está habilitado para su empresa»), y es normal.
Hay dos productos, con pasos distintos:
SEGURO DE LEY (60), paso a paso
Paso 1 · Consultar los planes con el chasis
curl -s -X POST "$API/v1/consultas" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"service_id":60,"identifier":"JTDBR32E720123456"}'
Respuesta real · 200 (recortada: trae 33 planes)
{
"flujo": "seguro_midasred",
"requiere_seleccion": true,
"opciones": [
{ "opcion_id": "mrseg:motocicleta125cc1:3m", "nombre": "MOTOCICLETA HASTA 250CC · Plan 1 - 3 Meses",
"precio": 150, "tipo_vehiculo_nombre": "MOTOCICLETA HASTA 250CC", "vigencia_texto": "3 meses" },
{ "opcion_id": "mrseg:automovil2cil1:12m", "nombre": "AUTOMOVIL/ JEEP/ STATION · Plan 3 - Anual",
"precio": 2000, "tipo_vehiculo_nombre": "AUTOMOVIL/ JEEP/ STATION", "vigencia_texto": "12 meses" },
{ "opcion_id": "mrseg:automovil2cil2:12m", "nombre": "AUTOMOVIL/ JEEP/ STATION + GRUA · Plan Anual-Grua",
"precio": 2800, "tipo_vehiculo_nombre": "AUTOMOVIL/ JEEP/ STATION + GRUA", "vigencia_texto": "12 meses" }
],
"datos_requeridos": ["cedula", "telefono"],
"mensaje": "Elija el tipo de vehículo y la vigencia."
}
Su pantalla pregunta dos cosas: qué tipo de vehículo es (moto, carro, camioneta,
autobús, camión) y por cuánto tiempo (3, 6 o 12 meses). Agrupe las opciones por
tipo_vehiculo_nombre para que el cajero no tenga que leer 33 renglones.
Paso 2 · Vender, con los datos del asegurado
curl -s -X POST "$API/v1/recargas" -H "$AUTH" \
-H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
-H "Content-Type: application/json" \
-d '{
"service_id": 60,
"identifier": "JTDBR32E720123456",
"opcion_id": "mrseg:motocicleta125cc1:3m",
"datos": { "cedula": "00112345678", "telefono": "8095551234" }
}'
datos.cedula: 11 dígitos (los guiones se ignoran).
datos.telefono: 10 dígitos que empiezan por 809, 829 u 849.
- No envíe
amount: el precio se lee del proveedor al cobrar.
El seguro no se puede anular
Ninguno de los dos productos acepta anulación. Confirme con el cliente el tipo de vehículo y
la vigencia antes de cobrar.
Una sola función para vender todo
No necesita un programa distinto por categoría. Basta con mirar el flujo.
Este ejemplo en JavaScript (Node 18 o más reciente) muestra la lógica completa.
// vender.js — ejemplo didáctico. En producción, las credenciales van en variables
// de entorno y esta función corre en SU servidor, nunca en el navegador del cliente.
const API = "https://api.recarga.do";
const AUTH = "Bearer " + process.env.RD_KEY + "." + process.env.RD_SECRET;
async function llamar(metodo, ruta, cuerpo, clave) {
const cabeceras = { "Authorization": AUTH, "Content-Type": "application/json" };
if (clave) cabeceras["Idempotency-Key"] = clave;
const r = await fetch(API + ruta, { method: metodo, headers: cabeceras,
body: cuerpo ? JSON.stringify(cuerpo) : undefined });
return { http: r.status, json: await r.json() };
}
// Paso de consulta: devuelve lo que la pantalla tiene que mostrar.
async function consultar(serviceId, identifier) {
const { http, json } = await llamar("POST", "/v1/consultas",
{ service_id: serviceId, identifier });
if (!json.success) throw new Error(json.error.message);
const d = json.data;
if (d.sin_deuda) return { tipo: "al_dia", titular: d.titular };
if (d.requiere_seleccion && d.opciones.length === 0) return { tipo: "sin_opciones" }; // p. ej. línea sin paquetes
if (d.requiere_seleccion) return { tipo: "elegir", titular: d.titular, opciones: d.opciones };
return { tipo: "monto", titular: d.titular, rango: d.monto };
}
// Paso de venta. `eleccion` es { amount } o { opcion_id }, según lo que eligió el cajero.
// La clave se genera UNA vez por venta y se reutiliza si hay que reintentar.
async function vender(serviceId, identifier, eleccion, clave = crypto.randomUUID(), datos) {
const cuerpo = { service_id: serviceId, identifier, ...eleccion, terminal_id: "CAJA-01" };
if (datos) cuerpo.datos = datos; // solo el seguro de ley
let res;
try {
res = await llamar("POST", "/v1/recargas", cuerpo, clave);
} catch (e) {
// Se cayó la red: no sabemos si se vendió. Reintentar con LA MISMA clave.
res = await llamar("POST", "/v1/recargas", cuerpo, clave);
}
const { http, json } = res;
if (http === 201) return { estado: "vendido", venta: json.data }; // guardar details si viene
if (http === 202) return { estado: "en_proceso", id: json.error.details.transaction_id };
return { estado: "rechazado", motivo: json.error.message }; // no se cobró
}
// Para una venta "en_proceso": preguntar cada 10 segundos hasta que se resuelva.
async function esperar(id) {
for (let i = 0; i < 30; i++) {
const { json } = await llamar("GET", "/v1/transacciones/" + id);
if (json.data.status !== "PENDING") return json.data.status; // SUCCESS o FAILED
await new Promise(r => setTimeout(r, 10000));
}
return "PENDING"; // sigue sin resolverse: dejarla en la lista del cierre de caja
}
// Ejemplos:
// const c = await consultar(50, "8094964444"); // paquetes → tipo "elegir"
// await vender(50, "8094964444", { opcion_id: c.opciones[0].opcion_id });
// await vender(1, "8095551235", { amount: 100 }); // recarga de celular
// const f = await consultar(9, "7001234567"); // factura de luz
// await vender(9, "7001234567", { opcion_id: f.opciones[0].opcion_id });
Si prefiere PHP o Python, las librerías de un solo archivo ya traen
esta lógica, y el punto de venta de ejemplo la muestra en una pantalla real.