Crear orden con referencia de pago

---

id: create-payment-reference-order title: Crear orden con referencia de pago sidebar_label: Crear orden (Yego Paycash) sidebar_position: 1

Crear orden con referencia de pago

Crea una orden en modalidad de prepago y genera una referencia de pago Yego Paycash asociada. El stock de los productos solicitados se reserva de inmediato y se mantiene reservado hasta que el pago sea confirmado o la referencia expire.

Autenticación

Este endpoint requiere un token Bearer emitido para tu cuenta de cliente.

Authorization: Bearer <tu_token>

Endpoint

POST /v1/shipments/prepaid-orders/payment-reference

Request

Headers

Header	Valor	Requerido
Authorization	Bearer <token>	Sí
Content-Type	application/json	Sí

Body

Campo	Tipo	Requerido	Longitud máxima	Descripción
unique_order_number	string	Sí	50	Identificador único de la orden, definido por el cliente.
total_price	decimal	Sí	5	Monto total de la orden.
warehouse_id	integer	Sí	10	Almacén desde el que se surtirá la orden.
reference_expiry_days	integer	No	1	Número de días que permanecerá vigente la referencia de pago Yego Paycash. Debe ser un valor entre 2 y 5. Si se omite, se utilizarán 2 días por defecto.
consignee	object	Sí	—	Datos de entrega. Ver tabla siguiente.
order_details	array	Sí	—	Lista de productos. Ver tabla siguiente.

reference_expiry_days es un campo opcional. Si no se proporciona, la referencia de pago se generará con una vigencia de 2 días.

Si se proporciona, el valor debe ser un número entero entre 2 y 5, incluyendo ambos valores.

consignee

Campo	Tipo	Requerido	Longitud máxima	Descripción
name	string	Sí	35	Nombre completo del destinatario.
country	string	Sí	20	País.
state	string	Sí	35	Estado.
municipality	string	Sí	35	Municipio.
neighborhood	string	Sí	35	Colonia.
street	string	Sí	24	Calle.
external_number	string	Sí	5	Número exterior.
internal_number	string	No	5	Número interior.
zipcode	string	Sí	5	Código postal a 5 dígitos.
email	string	No	50	Si se omite, se utiliza un correo genérico.
phone	string	Sí	10	Teléfono a 10 dígitos.
comments	string	No	250	Instrucciones adicionales de entrega.

order_details[]

Campo	Tipo	Requerido	Longitud máxima	Descripción
sku	string	Sí	35	SKU del producto.
quantity	integer	Sí	10	Cantidad solicitada.

Ejemplo de request

curl -X POST https://api.eon.example.com/api/v1/payment_references \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "unique_order_number": "PAYCASH-EXAMPLE",
    "total_price": 100.00,
    "warehouse_id": 1,
    "reference_expiry_days": 5,
    "consignee": {
      "name": "client name",
      "country": "mexico",
      "state": "san luis potosi",
      "municipality": "san luis potosi",
      "neighborhood": "XXXXXXXXXX",
      "street": "XXXXXXXXXX",
      "external_number": "000",
      "internal_number": null,
      "zipcode": "00000",
      "email": null,
      "phone": "4444444444",
      "comments": null
    },
    "order_details": [
      { "sku": "SKU-EXAMPLE", "quantity": 1 }
    ]
  }'

Si reference_expiry_days se omite, la referencia se generará automáticamente con una vigencia de 2 días.

Response

201 Created

{
    "code": 201,
    "success": {
        "arguments": {
            "reference": "1698353800048",
            "paycash_instructions_url": "https://sandboxpaycash.yego.mx/get-reference/MTY5ODM1MzgwMDA0ODoKICAgICAgICAgICAgICAgICAgICAkMTUwMC4wMDoKICAgICAgICAgICAgICAgICAgICAxMC8wOS8yMDI2CiAgICAgICAgICAgICAgICA="
        },
        "type": "order.created",
        "message": "Order created successfully. "
    }
}

Campo	Descripción
reference	Referencia de pago Yego Paycash para que el comprador pague en tienda.
paycash_instructions_url	Enlace a las instrucciones de pago, incluyendo el código de barras.

Errores

Status	Código de error	Causa
401	unauthorized	Token Bearer ausente o inválido.
404	client_not_found	El cliente asociado al token no existe o fue desactivado.
409	client_reference_already_exists	Ya existe una orden con ese unique_order_number para este cliente.
409	order_already_processing	Ya hay una solicitud en curso con el mismo unique_order_number (doble envío simultáneo).
422	client_not_authorized	El cliente no tiene un método de fulfillment habilitado.
422	invalid_address	Uno o más campos de consignee no pasaron la validación de formato.
422	invalid_reference_expiry_days	reference_expiry_days debe ser un número entero entre 2 y 5, incluyendo ambos valores.
422	no_shipping_service_coverage	Ninguna paquetería tiene cobertura para el código postal indicado.
422	product_not_found	Uno o más SKUs no existen o no pertenecen a este cliente.
422	insufficient_stock	No hay stock suficiente para uno o más productos en el almacén indicado.
503	payment_reference_creation_failed	Falla temporal al generar la referencia con Yego Paycash. Reintentar.

Ejemplo de error

{
    "code": 422,
    "fault": {
        "arguments": [],
        "type": "order.invalid_reference_expiry_days",
        "message": "reference_expiry_days must be an integer between 2 and 5."
    }
}