Personaliza los recibos

Esta guía muestra cómo reemplazar el Bitmap predeterminado de los recibos que el SDK imprime automáticamente al final de una transacción. No cambia el momento de la impresión ni los datos de la transacción que se muestran.

Cómo funciona

El SDK emite dos recibos por transacción y puedes personalizar cada uno de forma independiente — uno, ambos o ninguno. Un recibo que no personalizas mantiene el diseño predeterminado del SDK.

Recibo	Destinatario	Contenido predeterminado
Establecimiento (`EstablishmentReceipt`)	Lo conserva el comercio para la conciliación.	Incluye datos operativos adicionales (ARQC, AID, nombre del titular, terminal).
Cliente (`CustomerReceipt`)	Se entrega al titular de la tarjeta.	Solo los datos esenciales del recibo, sin datos sensibles de la tarjeta.

Cada provider recibe un objeto tipado con los datos de la transacción y devuelve el Bitmap que se va a imprimir. El SDK lo imprime en el momento adecuado.

ApoloSdk.Builder(context)
    .customizeReceipts {
        establishment(provider: EstablishmentReceiptBitmapProvider)
        customer(provider: CustomerReceiptBitmapProvider)
    }
    .setAutoPrintEstablishmentReceipt(autoPrint: Boolean)

typealias EstablishmentReceiptBitmapProvider = (EstablishmentReceipt) -> Bitmap
typealias CustomerReceiptBitmapProvider = (CustomerReceipt) -> Bitmap

setAutoPrintEstablishmentReceipt(true) (valor predeterminado) imprime el recibo del establecimiento automáticamente después de una venta aprobada, y la pantalla de éxito muestra solo el botón del recibo del cliente. Con false, no se imprime nada automáticamente y la pantalla de éxito muestra ambos botones.

Personaliza uno o ambos recibos

// only the customer receipt
ApoloSdk.Builder(applicationContext)
    .customizeReceipts {
        customer { receipt -> renderCustomerReceiptBitmap(receipt) }
    }
    .build()

// both receipts
ApoloSdk.Builder(applicationContext)
    .customizeReceipts {
        establishment { receipt -> renderEstablishmentReceiptBitmap(receipt) }
        customer { receipt -> renderCustomerReceiptBitmap(receipt) }
    }
    .setAutoPrintEstablishmentReceipt(true) // default — may be omitted
    .build()

Datos del recibo

El SDK entrega estos campos al provider. Algunos son exclusivos del recibo del establecimiento por privacidad, según la recomendación de ABECS.

Campo	Establecimiento	Cliente	Descripción
`merchantName`, `merchantDocument`, `merchantCity`	✅	✅	Identificación del comercio.
`terminalCode`	✅	✅	Terminal donde se realizó la transacción.
`cardBrand`, `cardNumber`	✅	✅	Marca de tarjeta y número enmascarado.
`cardholderName`	✅	—	Nombre del titular de la tarjeta — solo establecimiento.
`paymentMethod`	✅	✅	Medio de pago listo para mostrar.
`installments`, `installmentPlanLabel`	✅	✅	Cantidad de cuotas y etiqueta del plan (por ejemplo, `"5X DE R$ 200,00"`).
`installmentTypeLabel`	✅	—	Tipo de cuotas de crédito (por ejemplo, `"Parcelado Lojista"`) — solo establecimiento.
`amount`	✅	✅	Monto de la transacción formateado.
`authorizationCode`	✅	✅	Código de autorización.
`arqc`	✅	—	Criptograma ARQC — solo establecimiento.
`aid`	✅	✅	AID de la aplicación EMV.
`dateTime`	✅	✅	Fecha y hora de la transacción.
`isReprint`	✅	✅	`true` cuando la impresión es una reimpresión.
`paymentId`	✅	✅	Identificador de la transacción (útil para reembolsos posteriores).
`receiptType`	✅	✅	`DEBIT`, `CREDIT`, `PIX`, `VOUCHER` o `REVERSAL`.
`pinAuthApproved`, `requiresSignature`	✅	—	Indicadores de verificación del titular — solo establecimiento.
`voucherCategory`	✅	✅	Categoría del voucher, cuando corresponde.
`voucherCne`	✅	—	Código de red del voucher — solo establecimiento.
`voucherBalance`	—	✅	Saldo restante del voucher — solo cliente.
`originalAuthorizationCode`, `originalTerminal`	✅	✅	Datos de la transacción original, en los recibos de reembolso.

Puedes ramificar según receiptType para renderizar un diseño específico por medio de pago.

En Pix, los campos de tarjeta (cardBrand, cardNumber, cardholderName, arqc, aid, authorizationCode) llegan como cadenas vacías, porque no hay una tarjeta física. Usa paymentId como identificador principal y trata los campos vacíos para evitar errores de renderizado.

Buenas prácticas

Personaliza solo los recibos que necesitan diferenciarse del diseño predeterminado.
No incluyas datos sensibles exclusivos del establecimiento (cardholderName, arqc) en el recibo del cliente.
Devuelve un Bitmap con el tamaño adecuado para la impresora del terminal — las notas de resolución y contraste de Imprime un recibo también aplican aquí.

Siguientes pasos

Modelo de personalización — compara tema, slots, overrides y recibos.