☰ Menú · Transacciones
Referencia de la API

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.
locationobject
Solo cuando el ticket cayó en un local con reglas propias: {id, name, store_code, register_id, matched_by}. matched_by es register_id o store_id. Vea cómo enviar el local y la caja.
cashierobject
Solo si el ticket se envió con cashier: {id, name}.
memberobject
El socio después del ticket, con el saldo nuevo.
amount_refundedinteger
Total de las devoluciones parciales hasta ahora.
line_itemsarray
Las líneas del ticket y lo que hizo cada una: amount (la parte de la línea en el ticket), cashback_earned, earn_percent (null cuando la categoría no acumula), redeemable (se podía pagar con cashback) y quantity_refunded. Vacío cuando el ticket llegó sin líneas.
line_items[].promoboolean
Solo en locales con reglas de promoción: si la línea se envió como artículo en promoción.
displayobject
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. Si el propietario vinculó este código a un local, el ticket sigue las reglas de cashback del local.
store_idstring
El código de tienda (local) de su sistema contable, hasta 64 caracteres. Se usa cuando falta register_id o no está vinculado a ningún local. Si ambos apuntan a locales distintos, gana register_id. Vea cómo enviar el local y la caja.
cashierstring or object
Quién cobró el ticket, tal como lo conoce su caja: un texto (nombre o código) o {id, name}. Se guarda con el ticket y se devuelve en cashier. Nunca cambia el cashback y queda fuera de la comprobación de idempotencia. Las señales de cajeros del dueño lo usan para mostrar quién cobró un ticket sospechoso.
hold_iduuid
Captura esta reserva en lugar de enviar redeem_amount.
discount_typestring
Su código de descuento en este ticket (employee, discount_card, promo), hasta 64 caracteres. Con los tipos de descuento activados se aplican las reglas del propietario. Una línea también puede llevar su propio discount_type.
line_items[].promoboolean
true cuando el artículo está en promoción. Entonces las reglas de promoción del propietario deciden si la línea acumula y si se puede pagar con cashback. Se ignora si el local no activó la regla.
line_itemsarray
Hasta 500 elementos {sku, name, quantity, unit_price, category}. Se guardan con el ticket para los informes de productos y los usan las reglas de categoría: una categoría sin cashback, que no se puede pagar con cashback (productos en promoción) o con su propio porcentaje. Sin category buscamos la categoría por sku en el catálogo. Sin líneas, todo el ticket acumula al nivel del cliente.

Cómo enviar el local y la caja

Envíe dos cadenas opcionales con cada ticket (POST /v1/transactions), cálculo (POST /v1/checks/calculate) y reserva (POST /v1/holds): register_id es el código de la caja, store_id es el código de la tienda (local) en su sistema contable, hasta 64 caracteres. El propietario introduce ambos códigos en Locales. El local se busca primero por register_id; si falta el código de caja o no está vinculado a ningún local, por store_id. Si se envían ambos y apuntan a locales distintos, gana register_id. Si nada coincide, el ticket sigue las reglas generales y los códigos desconocidos aparecen al propietario en la lista "sin vincular". Los códigos funcionan cuando el local tiene activadas las reglas por local; si no, los campos se ignoran. Envíe ambos campos con cada ticket, aunque haya un solo local.

Solicitud · POST /v1/transactions
{
  "external_id": "000131",
  "member": "2000111703779",
  "amount": 12550,
  "store_id": "122927",
  "register_id": "122930",
  "line_items": [
    { "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "category": "106" },
    { "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 5550 }
  ]
}

El cálculo y la transacción llevan entonces un objeto location con el local en el que se calculó el ticket: id, name, store_code, register_id y matched_by (register_id o store_id). Sin location en la respuesta, el ticket siguió las reglas generales.

Respuesta · 201 (fragmento)
{
  "object": "transaction",
  "external_id": "000131",
  "register_id": "122930",
  ...
  "location": {
    "object": "location",
    "id": "3c1f5a7e-2b9d-4e60-8f14-6a0d2c7b9e35",
    "name": "Store 1",
    "store_code": "122927",
    "register_id": "122930",
    "matched_by": "register_id"
  }
}
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",
    "store_id": "S-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,
  "amount_refunded": 0,
  "line_items": [
    { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 400, "redeemable": true, "quantity_refunded": 0 },
    { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts", "amount": 17000, "earn_percent": 5, "cashback_earned": 850, "redeemable": true, "quantity_refunded": 0 }
  ],
  "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 parte de un ticket con cashback, por amount o por line_items. Por importe, el cashback se recalcula en proporción al ticket. Por líneas, el cashback sigue lo que cada línea acumuló realmente: un producto en promoción que no acumuló nada no resta nada, y el cashback gastado por el cliente vuelve solo por las líneas que podían pagarse con él. Envía tu propio external_id de la devolución; repetirlo es seguro. Se permiten varias devoluciones por ticket; la última cierra los restos exactos. Los tickets de programas con sellos y visitas se devuelven enteros con la anulación.

external_idstring, obligatorio
Tu id de esta devolución, hasta 128 caracteres.
amountinteger
El importe devuelto en unidades mínimas. No lo envíes cuando line_items indica lo devuelto.
line_itemsarray
Las líneas devueltas: {sku, quantity} o {name, quantity}, exactamente como en el ticket. Las unidades ya devueltas se descuentan; pedir más responde refund_exceeds_line con refundable. Un ticket enviado sin líneas responde no_line_items: devuélvelo por importe.
line_items[].promoboolean
Se acepta y se ignora: la devolución sigue lo que la línea original acumuló y podía pagar.
register_idstring
El id de tu caja, para la numeración por caja.
store_idstring
Su código de tienda. Se acepta por simetría con el ticket; la devolución sigue el local del ticket original.
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 }'

# or: the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000018", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
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,
  "line_items": [],
  "livemode": false,
  "created_at": "2026-10-06T18:40:02.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}

// by lines
{
  "object": "refund",
  "external_id": "RET-2026-000018",
  "transaction": "CHK-2026-000130",
  "amount": 4500,
  "cashback_reversed": 450,
  "redeem_restored": 0,
  "line_items": [
    { "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
  ],
  ...
}
POST/v1/transactions/{external_id}/returns
Permiso: transactions:write

Devuelve una o varias líneas de un ticket: el cliente trae de vuelta un artículo de tres. El cashback acumulado en esas líneas se retira y el cashback con el que las pagó vuelve, según lo que cada línea acumuló y con qué podía pagarse, nunca en proporción al ticket. La respuesta es el mismo objeto que una devolución con object: "return". Envía tu propio external_id de la devolución; repetirlo es seguro. Los tickets enviados sin line_items no se devuelven por líneas: devuélvelos por amount.

external_idstring, obligatorio
Tu id de esta devolución, hasta 128 caracteres.
line_itemsarray, obligatorio
Las líneas devueltas: {sku, quantity} o {name, quantity}, exactamente como en el ticket. Las unidades ya devueltas se descuentan; pedir más responde refund_exceeds_line con refundable.
line_items[].promoboolean
Se acepta y se ignora: la devolución sigue lo que la línea original acumuló y podía pagar.
register_idstring
El id de tu caja, para la numeración por caja.
store_idstring
Su código de tienda. Se acepta por simetría con el ticket; la devolución sigue el local del ticket original.
curl
# the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/returns \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000019", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
"Respuesta · 201"
{
  "object": "return",
  "id": "9f1c2b8e-5d7a-4e3f-9b21-0c4d6e8f1a23",
  "external_id": "RET-2026-000019",
  "transaction": "CHK-2026-000130",
  "amount": 4500,
  "cashback_reversed": 450,
  "redeem_restored": 0,
  "line_items": [
    { "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
  ],
  "livemode": false,
  "created_at": "2026-11-06T09:12:40.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 4500, "line_items": [ ... ], "member": { ... }, ... }
}
GET/v1/transactions
Permiso: transactions:write

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

Dudas sobre una integración: api@loyaltyfy.io. Respondemos en un día hábil.