Ir al contenido

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.
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.

Contra el sandbox, con una clave onx_test_…:

Ventana de terminal
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"
}
}'

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í

Cada código tiene su explicación en Errores.