Renew Payment Reference

Generates a new Yego Paycash payment reference for an existing prepaid order whose previous payment reference has expired.

The order must belong to the authenticated client. The new payment reference will have a fixed validity period of 2 days. The client cannot modify this period.

This endpoint does not create a new order. The original order remains unchanged, and the new payment reference is associated with it.

Renewal restrictions:

• The current payment reference must have expired.
• The order must not have a movement indicating that stock has been released.
• Each order can have its payment reference renewed only once.

Authentication

This endpoint requires a Bearer token issued for the client's account.

Authorization: Bearer <your_token>

Endpoint

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

Request

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes

Path parameters

Parameter	Type	Required	Max length	Description
unique_order_number	string	Yes	50	Unique order identifier provided by the client when the order was created.

Body

This endpoint does not require a request body. The new payment reference's validity period is automatically set to 2 days.

Request example

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

Validations

The following validations are performed before generating a new payment reference:

Validation	Description
Order existence	The order must exist and belong to the authenticated client.
Stock released	No movement indicating that the order's stock has been released must exist. If such a movement exists, the payment reference cannot be renewed.
Renewal limit	The order must not have a previous payment reference renewal movement. Only one renewal per order is allowed.
Reference expiration	The current payment reference must have expired. If it is still valid, a new reference cannot be generated.

If all validations pass, a new payment reference is generated and associated with the existing order, with a validity period of 2 days.

Response

200 OK

Returns the new payment reference and the payment instructions URL, including the barcode.

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

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

The new payment reference will be valid for 2 days. The client can subsequently use unique_order_number to check the order's payment status.

Errors

Status	Error code	Cause
401	unauthorized	Missing or invalid Bearer token.
404	order.not_found	No order exists for the specified unique_order_number and authenticated client.
409	payment_reference_not_expired	The current payment reference has not expired yet.
409	payment_reference_cannot_be_renewed	The payment reference cannot be renewed because a movement indicating that stock has been released exists.
409	payment_reference_limit_exceeded	The order has already used its single allowed renewal.
503	payment_reference_creation_failed	Temporary failure generating the new reference with Yego Paycash.

Error example: Payment reference has not expired

{
  "code": 409,
  "fault": {
    "arguments": {
      "current_reference": "1698353800048",
      "expiry_date": "2026-10-10T00:00:00Z"
    },
    "type": "order.payment_reference_not_expired",
    "message": "The payment reference has not expired yet."
  }
}

Error example: Renewal limit exceeded

{
  "code": 409,
  "fault": {
    "arguments": {},
    "type": "order.payment_reference_limit_exceeded",
    "message": "The order has reached its payment reference renewal limit."
  }
}