Servidor a servidor

API v1

Acceso restringido. No es un camino de autoservicio. No podés empezar esta integración hoy por tu cuenta: requiere certificación PCI del comercio y una URL provisionada individualmente por Tilopay.

Qué es#

El camino en el que los datos de tarjeta pasan por el servidor del comercio y este los envía al API de Tilopay.

Para quién es#

Es un servicio exclusivo para comercios que cuentan con certificación PCI.
La URL es personalizada por comercio, con una llave propia. No es una URL pública.

Por eso los ejemplos de esta página no traen una URL real: el Host y la llave del proxy se entregan a cada comercio aprobado.

Requisitos#

Certificación PCI vigente del comercio.
Cuenta Tilopay activa.
Solicitud aprobada, con la URL y la llave provisionadas por Tilopay para tu comercio.

Cómo se solicita#

Escribí a sac@tilopay.com con el nombre del comercio y el estado de tu certificación PCI. La URL y la llave se entregan directamente al comercio aprobado.

Referencia de la petición#

El Host y el header tx-proxy-key los entrega Tilopay a cada comercio aprobado. No hay una URL pública: los ejemplos usan marcadores.

POST / HTTP/1.1
Host: url provided by tilopay

Encabezados#

Authorizationstring#

bearer {token del API} — ver autenticación.

tx-proxy-keystring#

Llave del proxy de transacciones, provista por Tilopay.

Parámetros#

keystring#

Llave relacionada con el comercio (obligatorio).

cardstring#

Número de tarjeta (obligatorio).

cvvstring#

Código de seguridad (obligatorio).

expirestring#

Fecha de expiración en formato mesAño, por ejemplo 1023 (obligatorio).

namestring#

Nombre del tarjetahabiente (requerido).

lastnamestring#

Apellidos del tarjetahabiente (requerido).

phonestring#

Teléfono del cliente (requerido).

emailstring#

Correo del cliente (obligatorio).

addressstring#

Dirección del cliente (requerido).

citystring#

Ciudad del cliente (requerido).

statestring#

Estado en formato ISO, por ejemplo CR-SJ (San José, Costa Rica) o US-CA (California, EEUU) (requerido).

zipcodestring#

Código postal (requerido).

countrystring#

País en código ISO Alpha-2, por ejemplo CR, US, GT (requerido).

amountstring#

Monto de la compra (obligatorio).

currencystring#

Moneda en formato ISO, por ejemplo USD, CRC, GTQ (obligatorio).

orderNumberstring#

Número de orden (obligatorio).

capturenumber#

1 captura y autoriza, 0 solo autoriza (obligatorio).

redirectstring#

URL de respuesta (obligatorio).

Los campos shipTo* (shipToFirstName, shipToLastName, shipToAddress, shipToAddress2, shipToCity, shipToState, shipToZipPostCode, shipToCountry, shipToTelephone) aparecen en los ejemplos de la colección como datos de envío.

Petición#

{
  "key": "key",
  "card": "card PAN",
  "cvv": "CVV Number",
  "expire": "1023",
  "name": "firstname",
  "lastname": "lastname",
  "phone": "88888888",
  "email": "email@user.com",
  "address": "user address",
  "city": "city",
  "state": "state",
  "zipcode": "zipcode",
  "country": "country",
  "shipToFirstName": "Nombre",
  "shipToLastName": "Apellido",
  "shipToAddress": "San Jose",
  "shipToAddress2": "Escazu",
  "shipToCity": "San Jose",
  "shipToState": "SJ",
  "shipToZipPostCode": "10101",
  "shipToCountry": "CR",
  "shipToTelephone": "88778877",
  "amount": "amount",
  "currency": "currency code",
  "orderNumber": "Order Number",
  "capture": 1,
  "redirect": "url to redirect"
}

La colección incluye dos ejemplos, con 3DS y sin 3DS, con el mismo cuerpo de petición.

Respuesta#

{
  "code": "1",
  "description": "Transaccion aprobada",
  "auth": "123456",
  "orderNumber": "12345",
  "urlRedirect": "",
  "error": ""
}

Cuando la transacción requiere autenticación 3DS, la respuesta trae la URL en urlRedirect; ahí es donde se envía al tarjetahabiente. Para interpretar code, description y error, ver convenciones de las respuestas y cómo leer una respuesta de error.

Alternativas sin certificación PCI#

Si no tenés certificación PCI, estos caminos evitan por completo ese alcance:

Hosted payment page — Tilopay hospeda el formulario.
SDK JavaScript — el formulario vive en tu página, pero los datos viajan del navegador directo a Tilopay.
Sin código — plugin o plataforma ya integrada.

Última verificación: 2026-08-28 · Responsable: equipo-integraciones

Ver como Markdown crudo