Renovar referencia de pago

Genera una nueva referencia de pago Yego Paycash para una orden prepago existente cuya referencia de pago anterior haya expirado.

La orden debe pertenecer al cliente autenticado. La nueva referencia tendrá una vigencia fija de 2 días. El cliente no puede modificar este periodo.

Este endpoint no crea una nueva orden. La orden original se conserva y la nueva referencia de pago queda asociada a ella.

Restricciones de renovación:

• La referencia de pago actual debe haber expirado.
• La orden no debe tener un movimiento que indique que el stock fue liberado.
• Cada orden solo puede renovar su referencia de pago una vez.

Autenticación

Este endpoint requiere un token Bearer emitido para la cuenta del cliente.

Authorization: Bearer <tu_token>

Endpoint

POST /v1/shipments/prepaid-orders/payment-reference/:unique_order_number/renew

Request

Headers

Header	Valor	Requerido
Authorization	Bearer <token>	Sí

Parámetros de ruta

Parámetro	Tipo	Requerido	Longitud máxima	Descripción
unique_order_number	string	Sí	50	Identificador único de la orden proporcionado por el cliente al crearla.

Body

Este endpoint no requiere un body. La vigencia de la nueva referencia se establece automáticamente en 2 días.

Ejemplo de request

curl -X POST \
  "https://api.eon.example.com/api/v1/shipments/prepaid-orders/payment-reference/PAYCASH-EXAMPLE/renew" \
  -H "Authorization: Bearer $TOKEN"

Validaciones

Antes de generar la nueva referencia, se realizan las siguientes validaciones:

Validación	Descripción
Existencia de la orden	La orden debe existir y estar asociada al cliente autenticado.
Stock liberado	No debe existir un movimiento que indique que el stock de la orden fue liberado. Si existe, la referencia no puede renovarse.
Límite de renovación	La orden no debe tener un movimiento previo de renovación de referencia de pago. Solo se permite una renovación por orden.
Vigencia de la referencia	La referencia de pago actual debe haber expirado. Si todavía está vigente, no se permite generar otra.

Si todas las validaciones se cumplen, se genera una nueva referencia de pago asociada a la orden existente, con una vigencia de 2 días.

Response

200 OK

Devuelve la nueva referencia de pago y el enlace a las instrucciones de pago, incluido el código de barras.

{
  "code": 200,
  "success": {
    "arguments": {
      "reference": "1698353800048",
      "paycash_instructions_url": "https://sandboxpaycash.yego.mx/get-reference/EXAMPLE"
    }
  }
}

Campo	Descripción
reference	Nueva referencia de pago Yego Paycash para que el comprador realice el pago en tienda.
paycash_instructions_url	Enlace a las instrucciones de pago, incluido el código de barras de la nueva referencia.

La nueva referencia tendrá una vigencia de 2 días. El cliente puede utilizar unique_order_number para consultar posteriormente el estado de pago de la orden.

Errores

Status	Código de error	Causa
401	unauthorized	Token Bearer ausente o inválido.
404	order.not_found	No existe una orden asociada al unique_order_number proporcionado para el cliente autenticado.
409	payment_reference_not_expired	La referencia de pago actual todavía está vigente.
409	payment_reference_cannot_be_renewed	La referencia no puede renovarse porque existe un movimiento que indica que el stock fue liberado.
409	payment_reference_limit_exceeded	La orden ya utilizó su única renovación permitida.
503	payment_reference_creation_failed	Fallo temporal al generar la nueva referencia con Yego Paycash.

Ejemplo de error: la referencia todavía está vigente

{
  "code": 409,
  "fault": {
    "arguments": {
      "current_reference": "1698353800048",
      "expiry_date": "2026-10-10T00:00:00Z"
    },
    "type": "order.payment_reference_not_expired",
    "message": "La referencia de pago todavía está vigente."
  }
}

Ejemplo de error: límite de renovación excedido

{
  "code": 409,
  "fault": {
    "arguments": {},
    "type": "order.payment_reference_limit_exceeded",
    "message": "La orden ya alcanzó el límite de renovaciones de su referencia de pago."
  }
}