Receiving the purchase

There is no separate webhook for n1coCupones. When the shopper pays, you receive the same SuccessPayment event the other n1co Business integrations already use, with the coupon or giftcard inside orderDetail.

Start from the webhook documentation

Endpoint configuration, the secret key, HMAC signature verification, the event object and the full SuccessPayment payload with its field table all live in Webhook.

This page only adds what is specific to coupons and giftcards.

What to store

Each element of orderDetail may carry a coupon object. That is the coupon or the giftcard:

"orderDetail": [
  {
    "name": "2 coffees of your choice + artisan bread",
    "price": "4.00",
    "quantity": "1",
    "coupon": {
      "code": "U6FWUW",
      "qrCodeUrl": "https://qr.n1co.shop/?chl=U6FWUW",
      "startDate": "2026-01-06T18:00:00",
      "endDate": "2026-03-31T18:00:00",
      "redemptionLimit": "1",
      "redemptionCount": "0",
      "status": "Unredeemed"
    }
  }
]

Field	What for
coupon.code	The code the customer will present. It is the key you validate against later.
coupon.startDate and coupon.endDate	The validity window.
coupon.status	State at purchase time. It arrives as Unredeemed.
quantity	Quantity for the line.

A line without a coupon object is a regular product, not a coupon: ignore it for this integration.

Numeric values travel as strings

Every number arrives quoted: "quantity": "1", not "quantity": 1. A parser expecting a numeric type will fail.

Coupon or giftcard

Both arrive the same way, inside coupon. What tells them apart sits at the root of the event, in orderType:

{
  "orderId": "52544",
  "orderType": "GIFTCARDS",
  "type": "SuccessPayment",
  "metadata": { "orderDetail": [ /* ... */ ] }
}

orderType	The order
COUPON_APP	Carries coupons only
GIFTCARDS	Carries at least one giftcard

orderType describes the whole order, not the line. In practice an order carries a single kind, but if a cart were to mix coupons and giftcards, the order would be labelled GIFTCARDS.

Use it to decide what to do with the amount, which is the only thing that differs between the two.

Giftcards: the amount

This only applies to giftcards (orderType: "GIFTCARDS"). A coupon contributes no amount to deduct: it already defines by itself what you hand over, so its price is informational and plays no part in the redemption.

For a giftcard, price is the value you will apply to the customer's bill, and picking the wrong field means overcharging them.

Three fields look alike. Only one is the giftcard's value

Field	Example		Why
orderDetail[].price	"10.00"	✅ Use this	It is the giftcard's value: the amount the shopper chose.
OrderTotalDetails.total	"10.25"	❌	Includes the purchase service fee. It is what the shopper paid, not what the giftcard is worth. That fee is not spendable balance.
OrderTotalDetails.subtotal	"10.00"	❌	It is the order total. It matches when a single giftcard is bought, but stops working once an order carries several.

Store that value alongside the code. At redemption, the cashier should never type it.

Next step

With the code in your database, the customer can come and redeem it: Redeeming the code.