Create Order with Payment Reference

Creates an order in prepaid mode and generates an associated Yego Paycash payment reference. Stock for the requested products is reserved immediately and remains reserved until payment is confirmed or the reference expires.

Authentication

This endpoint requires a Bearer token issued for your client account.

Authorization: Bearer <your_token>

Endpoint

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

Request

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes
Content-Type	application/json	Yes

Body

Field	Type	Required	Max length	Description
unique_order_number	string	Yes	50	Unique order identifier, defined by the client.
total_price	decimal	Yes	5	Total order amount.
warehouse_id	integer	Yes	10	Warehouse the order will be fulfilled from.
reference_expiry_days	integer	No	1	Number of days the Yego Paycash payment reference will remain valid. Must be between 2 and 5 days. Defaults to 2 when omitted.
consignee	object	Yes	—	Delivery information. See table below.
order_details	array	Yes	—	List of products. See table below.

reference_expiry_days is optional. If it is not provided, the payment reference will be generated with a validity period of 2 days.

When provided, the value must be an integer between 2 and 5, inclusive.

consignee

Field	Type	Required	Max length	Description
name	string	Yes	35	Recipient's full name.
country	string	Yes	20	Country.
state	string	Yes	35	State.
municipality	string	Yes	35	Municipality.
neighborhood	string	Yes	35	Neighborhood.
street	string	Yes	24	Street.
external_number	string	Yes	5	External number.
internal_number	string	No	5	Internal/apartment number.
zipcode	string	Yes	5	5-digit postal code.
email	string	No	50	A generic email is used if omitted.
phone	string	Yes	10	10-digit phone number.
comments	string	No	250	Additional delivery instructions.

order_details[]

Field	Type	Required	Max length	Description
sku	string	Yes	35	Product SKU.
quantity	integer	Yes	10	Quantity requested.

Request example

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 }
    ]
  }'

If reference_expiry_days is omitted, the reference will automatically be generated with a validity period of 2 days.

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

Field	Description
reference	Yego Paycash payment reference for the buyer to pay in-store.
paycash_instructions_url	Link to payment instructions, including the barcode.

Errors

Status	Error code	Cause
401	unauthorized	Missing or invalid Bearer token.
404	client_not_found	The client associated with the token does not exist or has been deactivated.
409	client_reference_already_exists	An order with that unique_order_number already exists for this client.
409	order_already_processing	A request with the same unique_order_number is already in progress (concurrent double submission).
422	client_not_authorized	The client does not have a fulfillment method enabled.
422	invalid_address	One or more consignee fields failed format validation.
422	invalid_reference_expiry_days	reference_expiry_days must be an integer between 2 and 5, inclusive.
422	no_shipping_service_coverage	No carrier has coverage for the given postal code.
422	product_not_found	One or more SKUs do not exist or do not belong to this client.
422	insufficient_stock	Insufficient stock for one or more products at the given warehouse.
503	payment_reference_creation_failed	Temporary failure generating the reference with Yego Paycash. Retry.

Error example

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