Ejemplos probados en el ambiente de pruebas

Cómo vender cada producto

Una guía para quien integra por primera vez: qué pide cada categoría, en qué orden se llama a la API y qué se le imprime al cliente. Todas las respuestas de esta página son reales, copiadas del ambiente de pruebas el 31 de octubre de 2026.

Lectura25 min Requisitosaber usar curl o Postman Costoninguno: es el simulador

Antes de empezar: cinco palabras

Si ya integró una API de pagos, salte a la regla de oro.

PalabraQué significa aquí
service_idEl número del producto. CLARO es el 1, EDESUR es el 9. Sale de GET /v1/servicios o del diccionario de productos.
identifierA quién o a qué se le vende: el teléfono, el contrato de luz, la cédula, la matrícula. Cada producto pide uno distinto.
flujoLa forma en que se vende ese producto. Hay cuatro, y son la clave de esta página.
opcion_idEl paquete, la factura o el plan que eligió el cliente. Lo da la API en la consulta; usted nunca lo inventa.
Idempotency-KeyUn código único que usted genera para cada venta. Si repite la llamada con el mismo código, la API no cobra dos veces. Ver Idempotencia, en el manual.

Las credenciales de prueba

Son públicas a propósito. No mueven dinero real ni hacen recargas reales. Pegue esto en su terminal una vez y todos los ejemplos de la página funcionarán tal cual:

KEY="rk_sbx_8c4cacb52c6b8f65bf389480ce3f8891"
SECRET="sk_sbx_a8e4de1dbd5e135a4be191cfd8901f386e541279a6550b1d30af9fbeaa65bbd0"
AUTH="Authorization: Bearer $KEY.$SECRET"
API="https://api.recarga.do"
¿En Windows sin terminal Linux?

Use la colección de Postman: trae las mismas credenciales. Los cuerpos JSON de esta página se pegan igual en Postman.

La regla de oro: el producto decide cómo se vende

No todo se vende "escribiendo un monto". Antes de programar una categoría, mire su flujo.

FlujoQuién pone el precioLlamadasEjemplos
monto_libreEl cliente, dentro de un mínimo y un máximo1. POST /v1/recargas con amountRecarga Claro, luz prepago, Betcris
paquetesEl operador. Los paquetes cambian según el número1. POST /v1/consultas
2. POST /v1/recargas con opcion_id
Claro Paquetes, Wind Paquetes
facturasLa empresa que cobra (distribuidora, universidad…)1. POST /v1/consultas
2. POST /v1/recargas con opcion_id
EDESUR, CAASD, Claro Postpago, DGII
segurosLa aseguradoraVarios pasos; ver SegurosSeguro de ley

No tiene que memorizar la tabla: cada servicio trae su flujo escrito. Pregúnteselo a la API:

curl -s "$API/v1/servicios" -H "$AUTH"
{
  "id": 50,
  "nombre": "Claro Paquetes",
  "categoria": "Paquetes de Datos",
  "flujo": "paquetes",
  "requiere_consulta": true,
  "como_comprar": "Consulte primero POST /v1/consultas para obtener los paquetes de ese número, y envíe el `opcion_id` elegido.",
  "monto_minimo": 0,
  "monto_maximo": 0,
  "acepta_anulacion": false
}

Si requiere_consulta es true, su pantalla tiene dos pasos: primero consultar y mostrar opciones, después cobrar. Si es false, basta un paso.

El error más común de un principiante

Programar todo como recarga de celular (con amount). Con un paquete o una factura, la API lo rechaza y le dice qué hacer. Mejor programarlo bien desde el principio.

Las categorías y su flujo

Cómo es una venta, de principio a fin

Es igual en todas las categorías. Solo cambia el paso 2.

1 · El cajero eligeProducto (service_id) y dato del cliente (identifier).
→
2 · ConsultarSolo si requiere_consulta. Muestra paquetes, facturas o el nombre del titular.
→
3 · CobrarPOST /v1/recargas con un Idempotency-Key nuevo.
→
4 · ImprimirSi fue 201: recibo con auth_code. Si fue 202: "en proceso".

Qué hacer con cada respuesta de la venta

RespuestaSignificaQué hace la caja
201 · SUCCESSVendido y cobrado de su saldoEntregar el recibo. Cobrarle al cliente
202 · TRANSACTION_PENDINGEl proveedor no ha contestado. El dinero queda retenidoNo repetir la venta. Consultar GET /v1/transacciones/{id} hasta que diga SUCCESS o FAILED
422 · VALIDATION_ERRORFaltó o sobró un dato. No se cobróMostrar el message al cajero y corregir
422 · INVALID_PHONE, TRANSACTION_REJECTEDEl operador rechazó. No se cobróAvisar al cliente. No reintentar igual
422 · INSUFFICIENT_BALANCESu cuenta no tiene saldoDepositar a Recarga.do. Ver Manejo del saldo
Sin respuesta, o 500No se sabeRepetir con el mismo Idempotency-Key. Así nunca se cobra dos veces

Esta es la respuesta real de un 202. El transaction_id es el que hay que consultar:

{
  "success": false,
  "error": {
    "code": "TRANSACTION_PENDING",
    "message": "La operación quedó en proceso. Consulte su estado antes de reintentar; el importe permanece retenido.",
    "details": {
      "transaction_id": 76678,
      "xid": "RD-6cb49142d86e0a729f9959be",
      "status": "PENDING",
      "consultar_en": "/v1/transacciones/76678"
    }
  },
  "request_id": "req_1f7e0aad8de993e7849c0ea4"
}
Nunca devuelva el efectivo de una venta en 202 sin consultar antes

Una venta en proceso puede terminar en SUCCESS minutos después. Si la caja ya devolvió el dinero, el cliente recibe su recarga y usted la paga. El manual lo explica con detalle en Flujos recomendados.

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.

ServicioIDFlujoidentifier
STARCABLE16facturasNúmero de contrato o cuenta
WIND18facturasNúmero de contrato o cuenta
WIND PAQUETES19paquetesNúmero de teléfono

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" }
]

⚡ Luz prepago

monto_libre

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.

💧 Agua

facturas

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.

ServicioIDMontosidentifier
BETCRIS32RD$100–5,000Número de cuenta
JUANCITO SPORT21RD$100–5,000Número de cuenta
SUPERBETS61RD$100–15,000Número de cuenta
OROBET62RD$100–180,000Número de cuenta
PASO RÁPIDO26RD$100–1,500Número del tag del vehículo
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.

ServicioIDidentifier
CREDIGO · MONEYSHOP · SOLUCREDITO37 · 35 · 34Número de contrato o cuenta del préstamo
DGII47RNC o cédula
TSS48RNC del empleador
INFOTEP49RNC de la empresa
PGR MULTAS39Número de multa o cédula
UAPA · UNAPEC · UNIBE · UTEL42 · 44 · 45 · 43Matrícula del estudiante
AVON40Código de representante
BELCORP41Código de consultora
ADN · ASTER · COAAROM · KRECE · PAYCASH · LUZ Y FUERZA46 · 25 · 24 · 59 · 57 · 28Número de contrato o cuenta

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:

ProductoIDidentifierCómo se vende
SEGURO DE LEY60Chasis del vehículo (5 a 17 letras y números)Consultar planes → vender con opcion_id y los datos del asegurado
SEGURO (Seguro Dominicana)12PlacaSiete pasos con código SMS al dueño. Ver el manual: Seguro de ley

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.

Cómo probar cada caso sin gastar dinero

En el ambiente de pruebas, el último dígito del identifier decide qué pasa. Úselo para ver cómo reacciona su pantalla ante cada situación.

Termina enEn la consultaEn la venta
0502 QUERY_FAILED · "El número indicado no es válido o no pertenece a este operador."422 INVALID_PHONE · no se cobra
1Sin opciones: línea sin paquetes, o contrato al día (sin_deuda: true)422 TRANSACTION_REJECTED · no se cobra
2502 QUERY_FAILED · "El proveedor no respondió a tiempo."202 TRANSACTION_PENDING · el saldo queda retenido y en pruebas termina en FAILED en menos de 5 minutos
OtroRespuesta normal201 SUCCESS

Esta regla solo existe en el simulador. En producción el último dígito no significa nada.

Lista para practicar

Haga estas diez ventas antes de pedir sus credenciales de producción. Si su pantalla se comporta bien en todas, está listo.

  1. Recarga Claro de RD$100 a 8095551235. Debe imprimir el recibo.
  2. Recarga Claro de RD$5,000. Debe mostrar "monto máximo RD$2,000" sin cobrar.
  3. Recarga a 80955512 (8 dígitos). Debe pedir corregir el número.
  4. Recarga a 8095551232. Debe mostrar "en proceso" y no devolver el efectivo hasta consultar.
  5. Paquete Claro a 8094964444. Debe listar 4 paquetes y vender el elegido.
  6. Paquete Claro a 8094964441. Debe decir "este número no tiene paquetes".
  7. Factura EDESUR del contrato 7001234567. Debe mostrar titular, dirección y facturas.
  8. Factura EDESUR del contrato 7001234561. Debe decir "está al día".
  9. Abono de RD$1,000 a la factura del punto 7.
  10. Luz prepago EDESUR (22) de RD$500. Debe imprimir el token_recarga.
La cuenta de prueba es compartida

Otros integradores usan las mismas credenciales. Si recibe INSUFFICIENT_BALANCE, no es su código: pida a soporte una cuenta de pruebas propia.

Preguntas frecuentes

¿Cuánto gano en cada venta?

La API descuenta de su saldo el valor de la venta (amount). Su ganancia es la comisión que tenga acordada con Recarga.do. Ver §4 de la guía.

¿Puedo anular una venta?

Solo si el servicio tiene acepta_anulacion: true, con POST /v1/transacciones/{id}/anular. Las recargas de Claro y Altice se pueden anular; los paquetes y los seguros no. Ver el manual: Transacciones.

¿Tengo que consultar antes de una recarga de celular?

No. Es opcional en monto_libre. En luz prepago se recomienda, porque confirma el titular.

¿Puedo guardar la lista de paquetes o facturas para no consultar cada vez?

No. Cambian según el número y con el tiempo. Una factura que se pagó en otra parte ya no está pendiente, y la API lo rechazará con opcion_id: "no_disponible".

¿Las consultas cuestan dinero?

No mueven saldo. Pero cuentan para el límite de peticiones de su cuenta: consulte cuando el cajero lo pida, no en bucle. Ver Límites, en el manual.

Los paquetes y facturas del ambiente de pruebas no se parecen a los reales.

Es un catálogo de ejemplo, para programar contra la forma de los datos. Si necesita ver los reales mientras prueba, pida que activen consultas_reales en su token: la consulta será real y la venta seguirá simulada. El campo origen_datos le dice cuál está viendo.

¿Cuánto dura mi credencial y cómo la renuevo?

No vence cada pocos minutos ni hay que renovarla. Su api_key y su api_secret se envían en cada petición, sin iniciar sesión, y funcionan hasta que pase la fecha de vencimiento que Recarga.do le haya puesto (muchas credenciales no tienen ninguna) o hasta que se revoque. La credencial pública de pruebas de esta página no vence.

Cuando vence, todas las peticiones responden 401 UNAUTHENTICATED con el mensaje «El token expiró el …», con la fecha. Su saldo y sus ventas no se tocan.

Para renovarla: pídale una credencial nueva a su ejecutivo de cuenta o a soporte (no hay un botón ni una llamada de la API para hacerlo usted). Cambie el par en la configuración de su servidor y listo. Pida también una nueva si cree que alguien vio su api_secret.

No reintente un 401: con credenciales malas, varios intentos fallidos seguidos bloquean la credencial 15 minutos (429 AUTH_THROTTLED).

¿Qué es terminal_id?

Un nombre libre para su caja ("CAJA-01", "SUCURSAL-NORTE"), hasta 50 caracteres. Se guarda con la venta y le ayuda a cuadrar cada caja. Es opcional.

Algo no funciona. ¿Qué le mando a soporte?

El request_id de la respuesta (viene en todas, también en los errores) y, si hubo venta, el transaction_id. Con eso soporte encuentra su operación en segundos.