Skip to main content
El servicio de autorización POS permite procesar pagos presenciales mediante el endpoint POST /authorize. Esta trama debe utilizarse cuando la transacción proviene de un canal presencial, como terminal POS, PinPad, dispositivo Android POS o integración de captura física de tarjeta.

​
Endpoint

POST /authorize

​
Request

{
  "frame_type": "pos",
  "merchant_identifier": "b656d278-f047-4e23-9fa5-96c5818b5c8d",
  "brand": "visa",
  "payment_method": {
    "card": [
      {
        "pan": "cifrado",
        "expiry_date": "cifrado",
        "card_sequence_number": "cifrado",
        "track1": "B4000222357994675^CHARLES^230420100558222222",
        "track2": "04000220130005421D230620100222222222"
      }
    ],
    "terminal": {
      "terminal_id": "POS00001",
      "pin_block": "7788E773618F7977"
    }
  },
  "card_holder": [
    {
      "first_name": "John",
      "last_name": "Smith"
    }
  ],
  "context": {
    "pos": {
      "pan_entry_mode": "05",
      "pin_entry_capability": "1",
      "condition_code": "00",
      "chip_condition_code": "0",
      "terminal_type": "0",
      "terminal_entry_capability": "0"
    }
  },
  "merchant": {
    "card_acceptor": {
      "card_acceptor_name": "ABC Supplies",
      "address": {
        "country": "PE",
        "city": "LIMA"
      }
    }
  },
  "transaction": {
    "currency": "604",
    "amount": "5000000",
    "meta": {
      "internal_operation_number": "123554",
      "additional_fields": {}
    }
  },
  "icc_related_data": {
    "vsdc_chip_data": true,
    "app_interchange_profile": "1800",
    "dedicated_file_name": "A0000000980840",
    "terminal_verification_result": "8000048000",
    "icc_transaction_date": "220607",
    "icc_transaction_type": "00",
    "transaction_currency": "604",
    "authorized_amount": "5000000",
    "other_amount": "5000000",
    "issuer_app_data": "06020A03A00000",
    "terminal_country_code": "604",
    "app_cryptogram": "B9E652BBD8FE30E5",
    "terminal_capability_profile": "E0F8C8",
    "app_transaction_counter": "0151",
    "unpredictable_number": "D28971EC"
  }
}

​
Descripción de campos

CampoTipoObligatorioLongitudDescripción
frame_typestringSíenumCanal de la transacción. Para POS debe enviarse pos.
merchant_identifierstring UUIDSí36Identificador único del comercio. Se entrega al registrar el comercio durante el onboarding.
brandstringSíenumMarca de la tarjeta. Valores permitidos: visa, mscd.
payment_method.card[].panstringSí13-19Número de tarjeta cifrado.
payment_method.card[].expiry_datestringSí4Fecha de expiración cifrada.
payment_method.card[].card_sequence_numberstringNo1-3Número de secuencia de tarjeta cifrado.
payment_method.card[].track1stringNovariableTrack 1 de banda magnética.
payment_method.card[].track2stringNovariableTrack 2 de banda magnética o chip.
payment_method.terminal.terminal_idstringSí1-8Identificador del terminal POS.
payment_method.terminal.pin_blockstringNo16PIN cifrado en bloque TDEA.
card_holder[].first_namestringNo1-26Nombre del tarjetahabiente.
card_holder[].last_namestringNo1-26Apellido del tarjetahabiente.
context.pos.pan_entry_modestringSí2Modo de entrada PAN. 05 = chip, 07 = contactless, 90 = banda magnética, 01 = manual.
context.pos.pin_entry_capabilitystringSí1Capacidad de captura de PIN. 0 = no puede capturar PIN, 1 = puede capturar PIN.
context.pos.condition_codestringSí2Código de condición POS. 00 = transacción presencial normal.
context.pos.chip_condition_codestringNo1Condición del chip. 0 = no aplica, 1 = chip no leído.
context.pos.terminal_typestringNo1Tipo de terminal.
context.pos.terminal_entry_capabilitystringNo1Capacidad de entrada del terminal.
merchant.card_acceptor.card_acceptor_namestringNo1-25Nombre del comercio. Puede utilizarse como override.
merchant.card_acceptor.address.countrystringNo2País en formato ISO alpha-2.
merchant.card_acceptor.address.citystringNo1-13Ciudad del comercio.
transaction.currencystringSí3Código ISO 4217 numérico. Ejemplo: 604 = PEN, 840 = USD.
transaction.amountstringSí6-17Monto de la operación sin decimales.
transaction.meta.internal_operation_numberstringSí1-40Referencia o número de operación del comercio. Debe ser único por comercio.
transaction.meta.additional_fieldsobjectNo—Campos libres enviados por el comercio en formato key-value.
icc_related_data.vsdc_chip_databooleanSí, si es chip—Indica que la transacción contiene datos EMV.
icc_related_data.app_interchange_profilestringSí, si es chip4 hexAIP, Application Interchange Profile del chip.
icc_related_data.dedicated_file_namestringSí, si es chipvariable hexAID de la aplicación.
icc_related_data.terminal_verification_resultstringSí, si es chip10 hexTVR, Terminal Verification Result.
icc_related_data.icc_transaction_datestringSí, si es chip6Fecha de transacción ICC en formato YYMMDD.
icc_related_data.icc_transaction_typestringSí, si es chip2Tipo de transacción ICC. 00 = compra.
icc_related_data.transaction_currencystringSí, si es chip3Código ISO 4217 numérico.
icc_related_data.authorized_amountstringSí, si es chipvariableMonto autorizado.
icc_related_data.other_amountstringNovariableMonto adicional, por ejemplo cashback.
icc_related_data.issuer_app_datastringSí, si es chipvariable hexIAD, Issuer Application Data.
icc_related_data.terminal_country_codestringSí, si es chip3País del terminal en formato ISO numérico.
icc_related_data.app_cryptogramstringSí, si es chip16 hexTC o ARQC generado por el chip.
icc_related_data.terminal_capability_profilestringSí, si es chip6 hexCapacidades del terminal.
icc_related_data.app_transaction_counterstringSí, si es chip4 hexATC, Application Transaction Counter.
icc_related_data.unpredictable_numberstringSí, si es chip8 hexNúmero aleatorio generado por el terminal.

​
Valores permitidos

​
frame_type

ValorDescripción
posTransacción presencial.

​
brand

ValorDescripción
visaTransacción con tarjeta Visa.
mscdTransacción con tarjeta Mastercard.

​
context.pos.pan_entry_mode

ValorDescripción
01Entrada manual.
05Lectura por chip.
07Contactless.
90Banda magnética.

​
context.pos.pin_entry_capability

ValorDescripción
0El terminal no puede capturar PIN.
1El terminal puede capturar PIN.

​
context.pos.condition_code

ValorDescripción
00Transacción presencial normal.

​
context.pos.chip_condition_code

ValorDescripción
0No aplica.
1Chip no leído.

​
Objeto payment_method.card

Contiene la información de la tarjeta utilizada en la transacción POS. 
{
  "card": [
    {
      "pan": "cifrado",
      "expiry_date": "cifrado",
      "card_sequence_number": "cifrado",
      "track1": "B4000222357994675^CHARLES^230420100558222222",
      "track2": "04000220130005421D230620100222222222"
    }
  ]
}
CampoCifrado requeridoDescripción
panSíNúmero de tarjeta cifrado.
expiry_dateSíFecha de expiración cifrada.
card_sequence_numberSí, cuando apliqueNúmero de secuencia de tarjeta cifrado.
track1NoTrack 1 de banda magnética.
track2NoTrack 2 de banda magnética o chip.

​
Objeto payment_method.terminal

Contiene la información del terminal POS utilizado para capturar la transacción. 
{
  "terminal": {
    "terminal_id": "POS00001",
    "pin_block": "7788E773618F7977"
  }
}
CampoDescripción
terminal_idIdentificador del terminal POS.
pin_blockPIN cifrado en bloque TDEA. Debe enviarse cuando la operación requiera PIN.

​
Objeto context.pos

Contiene información del contexto de captura POS. 
{
  "context": {
    "pos": {
      "pan_entry_mode": "05",
      "pin_entry_capability": "1",
      "condition_code": "00",
      "chip_condition_code": "0",
      "terminal_type": "0",
      "terminal_entry_capability": "0"
    }
  }
}
CampoDescripción
pan_entry_modeModo de captura de la tarjeta. Debe reflejar el mecanismo real de captura.
pin_entry_capabilityIndica si el terminal tiene capacidad de capturar PIN.
condition_codeCondición bajo la cual se realiza la transacción POS.
chip_condition_codeCondición de lectura del chip, cuando aplique.
terminal_typeTipo de terminal utilizado.
terminal_entry_capabilityCapacidad de entrada del terminal.

​
Objeto merchant.card_acceptor

Permite enviar información referencial del comercio o realizar un override de datos de aceptación. 
{
  "merchant": {
    "card_acceptor": {
      "card_acceptor_name": "ABC Supplies",
      "address": {
        "country": "PE",
        "city": "LIMA"
      }
    }
  }
}
CampoDescripción
card_acceptor_nameNombre del comercio o nombre de aceptación.
address.countryPaís en formato ISO alpha-2.
address.cityCiudad del comercio.

​
Objeto transaction

Contiene la información transaccional de monto, moneda y referencia del comercio. 
{
  "transaction": {
    "currency": "604",
    "amount": "5000000",
    "meta": {
      "internal_operation_number": "123554",
      "additional_fields": {}
    }
  }
}
CampoDescripción
currencyCódigo ISO 4217 numérico.
amountMonto sin decimales.
meta.internal_operation_numberReferencia o número de operación del comercio.
meta.additional_fieldsCampos libres enviados por el comercio en formato key-value.
El objeto icc_related_data debe enviarse cuando la transacción sea chip o contactless EMV. 
{
  "icc_related_data": {
    "vsdc_chip_data": true,
    "app_interchange_profile": "1800",
    "dedicated_file_name": "A0000000980840",
    "terminal_verification_result": "8000048000",
    "icc_transaction_date": "220607",
    "icc_transaction_type": "00",
    "transaction_currency": "604",
    "authorized_amount": "5000000",
    "other_amount": "5000000",
    "issuer_app_data": "06020A03A00000",
    "terminal_country_code": "604",
    "app_cryptogram": "B9E652BBD8FE30E5",
    "terminal_capability_profile": "E0F8C8",
    "app_transaction_counter": "0151",
    "unpredictable_number": "D28971EC"
  }
}
CampoDescripción
vsdc_chip_dataIndica que la transacción contiene datos EMV.
app_interchange_profileAIP, Application Interchange Profile del chip.
dedicated_file_nameAID de la aplicación.
terminal_verification_resultTVR, Terminal Verification Result.
icc_transaction_dateFecha de transacción ICC en formato YYMMDD.
icc_transaction_typeTipo de transacción ICC. 00 = compra.
transaction_currencyCódigo ISO 4217 numérico.
authorized_amountMonto autorizado.
other_amountMonto adicional, por ejemplo cashback.
issuer_app_dataIAD, Issuer Application Data.
terminal_country_codePaís del terminal en formato ISO numérico.
app_cryptogramTC o ARQC generado por el chip.
terminal_capability_profileCapacidades del terminal.
app_transaction_counterATC, Application Transaction Counter.
unpredictable_numberNúmero aleatorio generado por el terminal.

​
Consideraciones sobre montos

El campo transaction.amount debe enviarse sin punto decimal. El monto se calcula aplicando el exponente de la moneda: 
Monto enviado = monto real × 10^exponente de la moneda
Ejemplo para moneda PEN:
Monto realCurrencyValor enviado
10.006041000
389.8060438980
50,000.006045000000

​
Consideraciones sobre moneda

El campo transaction.currency debe enviarse en formato ISO 4217 numérico.
MonedaCódigo ISO 4217 numérico
PEN604
USD840

​
Consideraciones sobre tarjeta

Los datos sensibles de tarjeta deben enviarse cifrados.
CampoCifrado requerido
payment_method.card[].panSí
payment_method.card[].expiry_dateSí
payment_method.card[].card_sequence_numberSí, cuando aplique

​
Consideraciones sobre EMV

Para operaciones chip o contactless EMV, debe enviarse el objeto icc_related_data.
Tipo de capturaRequiere icc_related_data
ChipSí
Contactless EMVSí
Banda magnéticaNo
ManualNo

​
Validaciones principales

Antes de enviar una autorización POS, validar lo siguiente:
ValidaciónRegla
Comerciomerchant_identifier debe estar activo y habilitado para operar.
Canalframe_type debe ser pos.
Marcabrand debe ser visa o mscd.
Terminalpayment_method.terminal.terminal_id debe estar registrado y habilitado.
Operacióntransaction.meta.internal_operation_number debe ser único por comercio.
Montotransaction.amount debe enviarse sin decimales.
Monedatransaction.currency debe enviarse en formato ISO 4217 numérico.
TarjetaLos campos sensibles deben enviarse cifrados.
PAN Entry Modecontext.pos.pan_entry_mode debe corresponder al modo real de captura.
PIN Capabilitycontext.pos.pin_entry_capability debe corresponder a la capacidad real del terminal.
ICCSi la operación es chip o contactless EMV, debe enviarse icc_related_data.

​
Ejemplo mínimo

El siguiente ejemplo muestra una autorización POS sin información EMV. 
{
  "frame_type": "pos",
  "merchant_identifier": "b656d278-f047-4e23-9fa5-96c5818b5c8d",
  "brand": "visa",
  "payment_method": {
    "card": [
      {
        "pan": "cifrado",
        "expiry_date": "cifrado"
      }
    ],
    "terminal": {
      "terminal_id": "POS00001"
    }
  },
  "context": {
    "pos": {
      "pan_entry_mode": "01",
      "pin_entry_capability": "0",
      "condition_code": "00"
    }
  },
  "transaction": {
    "currency": "604",
    "amount": "1000",
    "meta": {
      "internal_operation_number": "POS-000000001"
    }
  }
}

​
Ejemplo con chip EMV

{
  "frame_type": "pos",
  "merchant_identifier": "b656d278-f047-4e23-9fa5-96c5818b5c8d",
  "brand": "visa",
  "payment_method": {
    "card": [
      {
        "pan": "cifrado",
        "expiry_date": "cifrado",
        "card_sequence_number": "cifrado",
        "track2": "04000220130005421D230620100222222222"
      }
    ],
    "terminal": {
      "terminal_id": "POS00001",
      "pin_block": "7788E773618F7977"
    }
  },
  "context": {
    "pos": {
      "pan_entry_mode": "05",
      "pin_entry_capability": "1",
      "condition_code": "00",
      "chip_condition_code": "0",
      "terminal_type": "0",
      "terminal_entry_capability": "0"
    }
  },
  "transaction": {
    "currency": "604",
    "amount": "5000000",
    "meta": {
      "internal_operation_number": "POS-000000002",
      "additional_fields": {}
    }
  },
  "icc_related_data": {
    "vsdc_chip_data": true,
    "app_interchange_profile": "1800",
    "dedicated_file_name": "A0000000980840",
    "terminal_verification_result": "8000048000",
    "icc_transaction_date": "220607",
    "icc_transaction_type": "00",
    "transaction_currency": "604",
    "authorized_amount": "5000000",
    "other_amount": "0",
    "issuer_app_data": "06020A03A00000",
    "terminal_country_code": "604",
    "app_cryptogram": "B9E652BBD8FE30E5",
    "terminal_capability_profile": "E0F8C8",
    "app_transaction_counter": "0151",
    "unpredictable_number": "D28971EC"
  }
}

​
Response

La respuesta de una autorización POS se encuentra documentada en la página de respuesta general para autorizaciones.

Response de autorización

Ver estructura de respuesta para Ecommerce y POS.