☰ Menú · Transacciones
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
completedovoided.- 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_byesregister_idostore_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) yquantity_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_textyreceipt_linesen el idioma del cliente, listos para imprimir.
/v1/transactionsAplica 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_percentdel 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_ido no está vinculado a ningún local. Si ambos apuntan a locales distintos, ganaregister_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 encashier. 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 propiodiscount_type. - line_items[].promoboolean
truecuando 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. Sincategorybuscamos la categoría porskuen 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.
{
"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.
{
"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 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" }
]
}'{
"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, ... },
...
}
}/v1/transactions/{external_id}Devuelve una transacción a partir de tu id de ticket.
/v1/transactions/{external_id}/voidDeshace un ticket: se retiran el cashback y los sellos ganados y se devuelve el cashback canjeado. Anular dos veces no tiene efecto.
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
-H "Authorization: Bearer sk_test_..."{
"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, ... },
...
},
...
}/v1/transactions/{external_id}/refundsDevuelve 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_itemsindica 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 responderefund_exceeds_lineconrefundable. Un ticket enviado sin líneas respondeno_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.
# 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{
"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 }
],
...
}/v1/transactions/{external_id}/returnsDevuelve 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 responderefund_exceeds_lineconrefundable. - 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.
# 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{
"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": { ... }, ... }
}/v1/transactionsLista las transacciones, de más reciente a más antigua. Filtra con ?member=. Con paginación.