Construir el ticket desde la respuesta
El único parámetro externo a la respuesta que necesita el integrador es tipo_copia
(CLIENTE | COMERCIO), usado para la doble impresión (ver Doble impresión).
Cualquier otro dato del ticket debe obtenerse de la respuesta SOAP; lo que no esté en ella se marca
como constante de presentación o no derivable.
El recibo de venta solo se genera cuando la respuesta representa una operación aceptada:
| TIPO | RUTA | VALOR REQUERIDO |
|---|---|---|
| Resultado del servicio | GetNextMessageResponse/Result/Code | 0 |
| Código de operación | Message/MessageCode | 1000 |
SI Result/Code == "0" Y Message/MessageCode == "1000":
imprimir_ticket(PrintableData)
SI NO:
# Fuera de alcance (ver tabla de códigos de GetNextMessage en "Aceptar Cobros")
no_imprimir
Esta página cubre exclusivamente MessageCode = 1000. Un 1001 (cobro no efectivo) no imprime
ticket; otros códigos (10, 11) son pasos intermedios del circuito de GetNextMessage.
Referencia operativa, por parámetro, de todas las condiciones y acciones que el integrador debe contemplar. Cada apartado es autocontenido y se apoya solo en rutas SOAP.
Datos operacionales
| ETIQUETA | FUENTE | CONDICIÓN |
|---|---|---|
Tipo Operación: | PrintableData/OperationType | Siempre. |
Tarjeta: | PrintableData/CardNumber | Solo si NO es Bizum. |
IBAN Cliente: | mascara_iban (ver Bizum) | Solo si es Bizum. |
Nº de teléfono: | mascara_telefono (ver Bizum) | Solo si es Bizum. |
Ent. Aut.: | PrintableData/HCP | Siempre. |
AID: | PrintableData/AID | Solo si es_visa. |
ARC: | PrintableData/ACRCode | Siempre. |
Nº Autorización: | PrintableData/AuthorizationNumber | Siempre. |
Modo Autorización: | PrintableData/AuthorizationMode | Siempre. |
Modo Verificación: | PrintableData/DataVerificationType | Siempre. |
DDF: | PrintableData/DDFName | Siempre. |
Aplicación: | etiqueta_aplicacion | Siempre. |
Pasarela de Pagos: | SipayPlus | Constante. |
Extradata: | PrintableData/ContactlessLiteral | Siempre. |
A1. DataVerificationType — verificación del titular
PrintableData/DataVerificationType indica cómo autorizó la entidad la verificación del titular.
Determina si el ticket debe llevar recuadro de firma y/o una leyenda de verificación.
Esta variable es la imagen de cómo y bajo qué condiciones la entidad ha autorizado la transacción. De no respetar estas reglas, el ticket pasa a ser inválido ante un repudio bancario.
| VALOR | SIGNIFICADO | ¿RECUADRO DE FIRMA? | LEYENDA EN EL TICKET |
|---|---|---|---|
P | PIN | No | OPERACIÓN CON PIN FIRMA NO NECESARIA |
F | Firma | Sí | OPERACIÓN SIN PIN, FIRMA NECESARIA |
PF | PIN y Firma | Sí | OPERACIÓN CON PIN Y FIRMA |
D | Verificado por el dispositivo | No | VERIFICADO POR DISPOSITIVO |
* | Sin PIN ni firma (típico contactless de bajo importe) | No | Según ContactlessLiteral (ver A.2) |
Tabla de decisión de acciones (asumiendo NO DCC; para DCC ver A.3, que prevalece y fuerza firma en la copia de comercio):
SEGÚN DataVerificationType:
"F", "PF":
pintar_recuadro_firma() // método de autenticación = firma
imprimir_leyenda(segun_tabla)
"P":
imprimir_leyenda("OPERACIÓN CON PIN FIRMA NO NECESARIA")
"D":
imprimir_leyenda("VERIFICADO POR DISPOSITIVO")
"*":
SI ContactlessLiteral == "0":
imprimir_leyenda("OPERACIÓN SIN PIN NI FIRMA NECESARIA")
SI NO:
imprimir_leyenda("OPERACIÓN CONTACTLESS. FIRMA NO NECESARIA")
Devolución (OperationType == "Devolucion"): en la copia de cliente se pinta siempre el
recuadro FIRMA ESTABLECIMIENTO, con independencia de DataVerificationType.
En tarjeta chip pueden darse ambos escenarios: pedir firma (igual que un contactless) o no pedir
ni firma ni PIN sin ser contactless. Por eso la acción debe seguir siempre el valor recibido en
DataVerificationType, no el medio de entrada.
A2. ContactlessLiteral — logo de contactless
PrintableData/ContactlessLiteral indica si la operación fue sin contacto. En operaciones
contactless es obligatorio imprimir el logo de contactless.
Regla de decisión del logo:
SI ContactlessLiteral == "1" O ContactlessLiteral == "2":
imprimir_logo_contactless()
SI NO:
no_imprimir_logo()
ContactlessLiteral | ¿ES CONTACTLESS? | ACCIÓN |
|---|---|---|
1 | Sí | Imprimir logo de contactless. |
2 | Sí | Imprimir logo de contactless. |
0 (u otro valor) | No | No imprimir logo. |
ContactlessLiteral tiene un segundo uso: cuando DataVerificationType == "*" (ver A.1),
discrimina la leyenda de verificación —"0" → OPERACIÓN SIN PIN NI FIRMA NECESARIA; cualquier otro
valor → OPERACIÓN CONTACTLESS. FIRMA NO NECESARIA—. El valor también se imprime literalmente en la
fila Extradata: de los datos operacionales.
A3. Operación DCC (multi-divisa)
Una operación es DCC cuando extra/DCC/EXCHANGE_RATE viene alimentado (es_dcc = true, ver
Variables derivadas). En ese caso, los campos
multi-divisa son obligatorios en el ticket. PrintableData/Amount y PrintableData/CurrencySimbol
muestran el importe y la moneda seleccionados durante la transacción y siempre pueden usarse.
Checklist completo de acciones cuando es_dcc:
| # | CONDICIÓN | ACCIÓN |
|---|---|---|
| 1 | Siempre | Precio/producto en divisa de cobro: extra/DCC/DCC_AMOUNT + extra/DCC/DCC_CURRENCY_CODE (en vez de Amount + €). |
| 2 | Siempre | Total en divisa de transacción: dos líneas TRANSACTION CURRENCY y {Amount} {CurrencySimbol}. |
| 3 | Siempre | Imprimir bloque DCC Information: Exchange Rate = extra/DCC/EXCHANGE_RATE; DCC Merchant = extra/CARD_INFO/ADQ_BANK_NAME; Comission: = extra/DCC/COMMISION. |
| 4 | Mark up | extra/DCC/PERCENT_MARGIN_EXCHANGE_BCE vacío → {extra/DCC/MARK_UP}%; si no → MARK -UP on ECB RATE PUBLISHED ON {fecha} {PERCENT_MARGIN_EXCHANGE_BCE/1000}%. |
| 5 | Divisa ≠ EUR y rate válido | Línea Equivalencia: = equivalencia_divisa (1 {CurrencySimbol} = {rate} euros). |
| 6 | tipo_copia == COMERCIO | Pintar FIRMA CLIENTE (la firma en copia de comercio es obligatoria en DCC y prevalece sobre las reglas de DataVerificationType de A.1). |
| 7 | es_visa | Imprimir el disclaimer Visa Disclosure/Declaration… con PrintableData/CurrencySimbol. |
SI es_dcc:
precio = extra/DCC/DCC_AMOUNT + " " + extra/DCC/DCC_CURRENCY_CODE
total = ["TRANSACTION CURRENCY", PrintableData/Amount + " " + PrintableData/CurrencySimbol]
imprimir_bloque_DCC() // Exchange Rate, Equivalencia?, DCC Merchant, Mark up, Comission
SI tipo_copia == "COMERCIO":
pintar_recuadro_firma("FIRMA CLIENTE") // prevalece sobre A.1
SI es_visa:
imprimir_disclaimer_visa()
En DCC, no se aplican las leyendas de A.1 (P/D/*): la firma de la copia de comercio se rige
por la regla 6 de esta tabla. Los datos del subcampo extra/DCC (como mínimo EXCHANGE_RATE y el
operador DCC) son obligatorios en el ticket de una operación DCC.
| ETIQUETA | FUENTE / REGLA | CONDICIÓN |
|---|---|---|
DCC Information | Encabezado fijo | Siempre (dentro del bloque). |
Exchange Rate: | extra/DCC/EXCHANGE_RATE | Siempre. |
Equivalencia: | equivalencia_divisa | Solo si hay equivalencia (divisa ≠ EUR y rate válido). |
DCC Merchant: | extra/CARD_INFO/ADQ_BANK_NAME | Siempre. |
Mark up | Ver sub-regla | Siempre. |
Comission: | extra/DCC/COMMISION | Siempre. |
Sub-regla Mark up:
SI extra/DCC/PERCENT_MARGIN_EXCHANGE_BCE está vacío:
"{extra/DCC/MARK_UP}%" // p. ej. "***3,00%"
SI NO:
"MARK -UP on ECB RATE PUBLISHED ON {fecha} {PERCENT_MARGIN_EXCHANGE_BCE / 1000}%"
donde fecha = PrintableData/DateTime sin la hora
(quitar el patrón "- HH:MM:SS"; "02/02/2024 - 14:22:33" -> "02/02/2024 ")
Literales exactos: la etiqueta es Comission: y el texto ECB es
MARK -UP on ECB RATE PUBLISHED ON (respeta los espacios tal cual).
Disclaimer Visa (solo si es_dcc Y es_visa)
"Disclosure/Declaration
I accept that I have been offered a choice of currencies.
For payments and that this choice is final. I accept conversion rate, the final amount and that the
selected currency is {PrintableData/CurrencySimbol}"
Firma y leyenda de verificación
Combina PrintableData/OperationType, PrintableData/DataVerificationType,
PrintableData/ContactlessLiteral, es_dcc y tipo_copia. Pueden coincidir varias (p. ej. un
recuadro de firma y, por separado, una leyenda):
| # | CONDICIÓN | SALIDA |
|---|---|---|
| 1 | OperationType == "Devolucion" Y tipo_copia == CLIENTE | Recuadro FIRMA ESTABLECIMIENTO |
| 2 | es_dcc Y tipo_copia == COMERCIO | Recuadro FIRMA CLIENTE |
| 3 | DataVerificationType == "P" Y NO es_dcc | Leyenda OPERACIÓN CON PIN FIRMA NO NECESARIA |
| 4 | DataVerificationType == "D" Y NO es_dcc | Leyenda VERIFICADO POR DISPOSITIVO |
| 5 | DataVerificationType == "*" Y ContactlessLiteral == "0" Y NO es_dcc | Leyenda OPERACIÓN SIN PIN NI FIRMA NECESARIA |
| 6 | DataVerificationType == "*" Y ContactlessLiteral != "0" Y NO es_dcc | Leyenda OPERACIÓN CONTACTLESS. FIRMA NO NECESARIA |
Variables derivadas
Calcula estas variables solo a partir de rutas SOAP. Se usan en las reglas de impresión.
es_dcc — operación con conversión de divisa
es_dcc = (extra/DCC/EXCHANGE_RATE existe y no está vacío)
es_visa — marca Visa
familia = extra/CARD_INFO/FAMILY_NAME (MAYÚSCULAS, trim)
appLabel = PrintableData/AppLabel (MAYÚSCULAS, trim)
es_visa = (familia == "VISA") O (appLabel == "VISA")
etiqueta_aplicacion — texto de la fila "Aplicación"
SI es_bizum (ver sección Bizum):
etiqueta_aplicacion = "BIZUM"
SI NO, según PrintableData/AID:
"A000000333010102" -> "UPI Credit"
"A000000333010101" -> "UPI Debit"
"A000000333010103" -> "UPI Quasicredit"
cualquier otro -> PrintableData/AppLabel
importe_mostrado y divisa_mostrada
SI es_dcc:
importe_mostrado = extra/DCC/DCC_AMOUNT
divisa_mostrada = extra/DCC/DCC_CURRENCY_CODE // p. ej. "EUR"
SI NO:
importe_mostrado = PrintableData/Amount
divisa_mostrada = "€"