Beta privada · apertura 23 de diciembre
Declara una recarga por Yape o Plin
POST /v1/cuenta/recargas
Una persona paga por Yape o Plin y declara el pago: monto, método, número de operación, día del pago y la captura (voucher) en base64. La recarga queda en_revision hasta que la revisamos; se acredita una sola vez y luego te enviamos la factura. El mismo número de operación (o el mismo voucher) no se registra dos veces.
| Dato | Valor |
|---|---|
| Permiso | cuenta:recargar |
| Cobro | No cobra. |
Idempotency-Key |
Obligatoria |
| Herramienta MCP | No se ofrece a agentes. |
Parámetros
Sección titulada «Parámetros»| Nombre | En | Requerido | Tipo | Descripción |
|---|---|---|---|---|
Idempotency-Key |
header | Sí | string | Identifica una operación para que repetirla no la duplique. Si repites la petición con la misma clave y el mismo cuerpo, recibes la misma respuesta; con otro cuerpo, idempotencia_en_conflicto. Se guarda 24 horas. |
X-Request-Id |
header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. |
application/json, obligatorio. Los campos anidados van con punto y los de listas con []. No se aceptan campos desconocidos.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
monto |
string | Sí | Lo que pagaste. Hay un monto mínimo (S/ 20.00 por omisión). |
metodo |
“yape” | “plin” | Sí | |
numero_operacion |
string | Sí | Número de operación del pago, como lo muestra la app de Yape o Plin. |
fecha_pago |
string (date) | Sí | Día del pago según tu app, en hora de Lima. No puede ser futuro ni de hace más de 30 días. |
voucher |
object | Sí | Captura del pago en base64 (JPG, PNG o WEBP de hasta 5 MB). Revisamos el contenido real del archivo. |
voucher.tipo |
“image/jpeg” | “image/png” | “image/webp” | Sí | Formato del archivo: JPG, PNG o WEBP. |
voucher.contenido_base64 |
string | Sí | |
ruc_factura |
string | No | RUC para la factura de la recarga; si no lo envías, usamos el de tu cuenta. |
Ejemplo
Sección titulada «Ejemplo»Contra el sandbox, con una clave onx_test_…:
curl -X POST "https://api-sandbox.opennexum.com/v1/cuenta/recargas" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "monto": "1250.50", "metodo": "yape", "numero_operacion": "01234567", "fecha_pago": "2026-11-15", "voucher": { "tipo": "image/jpeg", "contenido_base64": "texto" }}'Respuestas
Sección titulada «Respuestas»Recarga registrada, en revisión.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
id |
string | Sí | Identificador que empieza con rec_. |
estado |
“en_revision” | “acreditada” | “rechazada” | Sí | en_revision hasta que una persona revisa el voucher; luego acreditada o rechazada (con motivo). |
monto |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
moneda |
“PEN” | Sí | |
metodo |
“yape” | “plin” | Sí | |
numero_operacion |
string | Sí | |
fecha_pago |
string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). |
ruc_factura |
string | null | Sí | |
motivo_rechazo |
string | null | Sí | Por qué se rechazó; null si no se rechazó. |
creada_en |
string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
revisada_en |
string (date-time) | null | Sí |
Errores
Sección titulada «Errores»Cada código tiene su explicación en Errores.
- 400
validacion - 401
clave_invalida - 403
permiso_faltante - 409
idempotencia_en_conflicto - 409
solicitud_en_curso - 409
ya_registrado - 409
estado_no_permite - 429
limite_uso - 500
error_interno - 501
operacion_no_disponible - 503
no_disponible