Desarrolladores

Referencia de la API

Una API REST predecible: recursos en plural, JSON de entrada y de salida, importes en la unidad mínima de la divisa y errores explícitos.

Obtener claves de prueba Guía de inicio

Referencia en proceso de alineación con la implementación: confirma cada firma con el equipo técnico antes de basarte en ella en producción. Este aviso debe eliminarse una vez validada la documentación.

URL base

Todas las peticiones se hacen por HTTPS sobre esta base. Las llamadas por HTTP simple se rechazan.

https://api.nexet.io/v1

La versión forma parte de la ruta. Solo se publica una nueva versión mayor ante un cambio incompatible; los campos nuevos se añaden sin cambiar de versión.

Autenticación

La autenticación usa tu clave secreta con autenticación HTTP básica: la clave es el usuario y la contraseña queda vacía.

curl https://api.nexet.io/v1/payments \
  -u sk_test_4dLm…:

Cada entorno tiene su par de claves: sk_test_… en sandbox y sk_live_… en producción.
La clave secreta nunca debe exponerse en el navegador ni subirse a un repositorio. Se revoca y se rota desde el espacio de comercio, sin cortes.

Idempotencia

Todos los endpoints de creación aceptan una cabecera Idempotency-Key. Repetir la misma clave devuelve la respuesta original en lugar de crear un segundo objeto: ningún pago duplicado ante un reintento de red.

-H "Idempotency-Key: ord-1042"

Errores

Los errores usan los códigos HTTP estándar y devuelven un objeto error que describe la causa. Facilita el identificador de la petición al soporte.

{
  "error": {
    "type": "card_declined",
    "code": "insufficient_funds",
    "message": "The card has insufficient funds.",
    "request_id": "req_8Kd92mLp"
  }
}

Código	type	Significado
400	invalid_request	Parámetro ausente o no válido.
401	authentication_error	Clave API ausente, no válida o revocada.
402	card_declined	Pago rechazado por el emisor de la tarjeta.
404	not_found	El recurso solicitado no existe.
409	idempotency_conflict	Clave de idempotencia reutilizada con un cuerpo distinto.
429	rate_limit	Demasiadas peticiones: reintenta con una espera creciente.
500	api_error	Incidencia del lado de Nexet Pay. La petición puede repetirse.

Paginación

Las listas se paginan por cursor: limit fija el tamaño de página y starting_after continúa después del identificador indicado. La respuesta indica si quedan más elementos.

GET /v1/payments?limit=50&starting_after=pay_3jF8dK2m

Pagos

Cobrar, consultar, capturar y reembolsar un pago.

POST	/v1/payments	Crear un pago (cobro inmediato o autorización).
GET	/v1/payments/{id}	Recuperar un pago y su estado.
GET	/v1/payments	Listar los pagos, con filtros por estado y por fecha.
POST	/v1/payments/{id}/capture	Capturar toda o parte de una autorización.
POST	/v1/payments/{id}/refunds	Reembolsar un pago, total o parcialmente.

Enlaces de pago

Crear enlaces de pago compartibles, con importe fijo o libre.

POST	/v1/payment_links	Crear un enlace de pago y su código QR.
GET	/v1/payment_links/{id}	Recuperar un enlace y su contador de pagos.
GET	/v1/payment_links	Listar los enlaces de pago.
POST	/v1/payment_links/{id}/deactivate	Desactivar un enlace antes de su fecha de caducidad.

Suscripciones

Definir planes y gestionar el ciclo de vida de las suscripciones.

POST	/v1/plans	Crear un plan de suscripción (importe, periodicidad, prueba).
POST	/v1/subscriptions	Suscribir a un cliente a un plan.
GET	/v1/subscriptions/{id}	Recuperar una suscripción y su ciclo en curso.
POST	/v1/subscriptions/{id}/cancel	Cancelar una suscripción, de inmediato o al final del periodo.

Facturas

Emitir facturas y seguir su cobro.

POST	/v1/invoices	Crear una factura con sus líneas y su IVA.
POST	/v1/invoices/{id}/send	Enviar la factura por correo con su botón de pago.
GET	/v1/invoices/{id}	Recuperar una factura y su estado de pago.
GET	/v1/invoices	Listar las facturas.

Clientes

Guardar a tus clientes y sus medios de pago tokenizados.

POST	/v1/customers	Crear un cliente y guardar sus medios de pago.
GET	/v1/customers/{id}	Recuperar un cliente.
GET	/v1/customers	Listar los clientes.

Webhooks

Declara una URL de endpoint desde tu espacio de comercio: cada evento se envía allí por POST, con reintentos exponenciales hasta recibir confirmación (respuesta 2xx).

Cada petición lleva una cabecera Nexet-Signature con la marca temporal y una firma HMAC del cuerpo. Verifícala antes de procesar el evento y rechaza las marcas temporales demasiado antiguas.

Nexet-Signature: t=1786982400,v1=5f2c…

Eventos emitidos

payment.succeededpayment.failedpayment.refundeddispute.openedsubscription.renewedsubscription.canceledinvoice.paidinvoice.payment_failedpayout.paid

Entorno de pruebas

La sandbox es gratuita e ilimitada. Las tarjetas de simulación permiten provocar cada escenario sin movimiento real de fondos.

Escenario	Resultado esperado
Pago aceptado	Estado succeeded, liquidación simulada.
Autenticación 3-D Secure requerida	Estado requires_action y luego redirección 3DS.
Tarjeta rechazada	Error card_declined con el motivo del rechazo.

La lista completa de tarjetas de prueba y de sus códigos de rechazo está disponible en tu espacio de comercio, pestaña Entorno de pruebas.

¿Alguna duda sobre la integración?

Cuéntanos tu caso de uso: nuestro equipo técnico responde en un día hábil.

Contactar con el equipo técnico