Transacciones

Un ticket cerrado que envía una caja. Genera recompensas, puede canjear cashback y se puede anular.

El objeto transaction

external_idstring: Tu id del ticket. Único por local.
statusstring: completed o voided.
amountinteger: El ticket completo, en unidades mínimas.
redeem_amountinteger: Lo pagado con cashback.
net_amountinteger: amount − redeem_amount.
cashback_earned, stamps_earnedinteger: Lo que generó el ticket.
reward_unlockedboolean: Este ticket completó una tarjeta de sellos.
currency, register_id, closed_atstring: Tal como se enviaron.
memberobject: El socio después del ticket, con el saldo nuevo.
amount_refundedinteger: Total de las devoluciones parciales hasta ahora.
displayobject: cashier_text y receipt_lines en el idioma del cliente, listos para imprimir.

Parámetro	Tipo	Descripción
external_id	string	Tu id del ticket. Único por local.
status	string	`completed` o `voided`.
amount	integer	El ticket completo, en unidades mínimas.
redeem_amount	integer	Lo pagado con cashback.
net_amount	integer	`amount − redeem_amount`.
cashback_earned, stamps_earned	integer	Lo que generó el ticket.
reward_unlocked	boolean	Este ticket completó una tarjeta de sellos.
currency, register_id, closed_at	string	Tal como se enviaron.
member	object	El socio después del ticket, con el saldo nuevo.
amount_refunded	integer	Total de las devoluciones parciales hasta ahora.
display	object	`cashier_text` y `receipt_lines` en el idioma del cliente, listos para imprimir.

POST/v1/transactions

Permiso: transactions:write

Aplica un ticket cerrado. Si repites un external_id, recibes el resultado guardado con 200. Se aceptan card_number y gross_amount como alias de member y amount.

external_idstring, obligatorio: Tu id del ticket, hasta 128 caracteres.
memberstring, obligatorio: Número de tarjeta, valor escaneado, número de serie, id de socio o teléfono.
amountinteger, obligatorio: El ticket completo antes del cashback, en unidades mínimas, mayor que cero.
redeem_amountinteger: Cashback que el cliente usa en este ticket. Por defecto, 0. Limitado por el saldo y por el redeem_max_percent del programa.
currencystring: ISO 4217. Por defecto, la moneda del programa.
closed_atdatetime: Cuándo se cerró el ticket, en ISO 8601 con desfase horario. Por defecto, ahora.
register_idstring: El id de tu caja o sede. Aparece en los informes.
hold_iduuid: Captura esta reserva en lugar de enviar redeem_amount.
line_itemsarray: Hasta 500 elementos {sku, name, quantity, unit_price, category}. Se guardan con el ticket para los informes de productos del local. No cambian lo que gana el cliente: los programas cuentan el importe del ticket.

Parámetro	Tipo	Descripción
external_id	string, obligatorio	Tu id del ticket, hasta 128 caracteres.
member	string, obligatorio	Número de tarjeta, valor escaneado, número de serie, id de socio o teléfono.
amount	integer, obligatorio	El ticket completo antes del cashback, en unidades mínimas, mayor que cero.
redeem_amount	integer	Cashback que el cliente usa en este ticket. Por defecto, 0. Limitado por el saldo y por el `redeem_max_percent` del programa.
currency	string	ISO 4217. Por defecto, la moneda del programa.
closed_at	datetime	Cuándo se cerró el ticket, en ISO 8601 con desfase horario. Por defecto, ahora.
register_id	string	El id de tu caja o sede. Aparece en los informes.
hold_id	uuid	Captura esta reserva en lugar de enviar `redeem_amount`.
line_items	array	Hasta 500 elementos `{sku, name, quantity, unit_price, category}`. Se guardan con el ticket para los informes de productos del local. No cambian lo que gana el cliente: los programas cuentan el importe del ticket.

curl

curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CHK-2026-000123",
    "member": "2000111703779",
    "amount": 25000,
    "currency": "MDL",
    "register_id": "POS-1",
    "closed_at": "2026-10-06T18:17:00+03:00",
    "line_items": [
      { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee" },
      { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts" }
    ]
  }'

Respuesta · 201

{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "completed",
  "amount": 25000,
  "redeem_amount": 0,
  "cashback_earned": 1250,
  "stamps_earned": 0,
  "reward_unlocked": false,
  "net_amount": 25000,
  "currency": "MDL",
  "register_id": "POS-1",
  "closed_at": "2026-10-06T15:17:00+00:00",
  "livemode": false,
  "created_at": "2026-10-06T18:17:17.921+00:00",
  "voided_at": null,
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
    ...
  }
}

GET/v1/transactions/{external_id}

Permiso: transactions:write

Devuelve una transacción a partir de tu id de ticket.

POST/v1/transactions/{external_id}/void

Permiso: transactions:write

Deshace un ticket: se retiran el cashback y los sellos ganados y se devuelve el cashback canjeado. Anular dos veces no tiene efecto.

curl

curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."

Respuesta · 200

{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "voided",
  "amount": 25000,
  "cashback_earned": 1250,
  "voided_at": "2026-10-06T18:17:21.003+00:00",
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 0, "currency": "MDL", "earn_rate": 5, ... },
    ...
  },
  ...
}

POST/v1/transactions/{external_id}/refunds

Permiso: transactions:write

Devuelve una parte de un ticket de cashback. El cashback ganado por esa parte se retira y el cashback que el cliente pagó por ella se le devuelve, en proporción a amount. Envía un external_id propio para la devolución; repetirlo no tiene riesgo. Se permiten varias devoluciones por ticket; la última ajusta los restos exactos. Los tickets de sellos y de visitas se devuelven enteros con void.

curl

# the guest returns 50.00 of a 200.00 check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000124/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000017", "amount": 5000 }'

Respuesta · 201

{
  "object": "refund",
  "id": "c41d2f7a-3b9e-4c11-8e0f-6a2d5b7c9e13",
  "external_id": "RET-2026-000017",
  "transaction": "CHK-2026-000124",
  "amount": 5000,
  "cashback_reversed": 200,
  "redeem_restored": 1000,
  "livemode": false,
  "created_at": "2026-10-06T18:40:02.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}

GET/v1/transactions

Permiso: transactions:write

Lista las transacciones, de más reciente a más antigua. Filtra con ?member=. Con paginación.