Hosted payment page

API v1

POST /api/v1/processPayment

Qué hace#

Devuelve la URL del formulario de pago para una compra.

Autenticación#

Requiere el token bearer del API en el header Authorization — ver autenticación.

Parámetros#

redirectstringrequerido#

Sitio donde esperás la respuesta de la transacción, por ejemplo mywebsite.com. Debe soportar el método GET. Ejemplo de respuesta al redirect: mywebsite.com?code=1&description=Transaction%20is%20approved.&auth=123456&order=TPYS-881WROIBQA1405468&tpt=4300&crd=&tilopay-transaction=4300&OrderHash=b02927cb...&returnData=Tilopay-dataReturn123456789&form_update=ok. Si code = 1 la transacción está aprobada; en cualquier otro caso, rechazada. OrderHash es un string único por transacción: su algoritmo no es público y se solicita escribiendo a soporte@tilopay.com.

keystringrequerido#

Llave relacionada con el cliente. Se obtiene en Panel administrativo · Integración con plataformas.

amountstringrequerido#

Monto de la compra.

currencystringrequerido#

Moneda de la compra en formato ISO, por ejemplo USD, CRC, GTQ.

orderNumberstringrequerido#

Número de orden, puede ser alfanumérico.

capturestringrequerido#

Captura y autoriza: 1 sí, 0 no.

billToFirstNamestringrequerido#

Nombre.

billToLastNamestringrequerido#

Apellidos.

billToAddressstringrequerido#

Dirección.

billToAddress2stringrequerido#

Dirección 2.

billToCitystringrequerido#

Ciudad.

billToStatestringrequerido#

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

billToZipPostCodestringrequerido#

Código postal.

billToCountrystringrequerido#

País en código ISO Alpha-2, por ejemplo CR (Costa Rica), US (EE. UU.) o GT (Guatemala).

billToTelephonestringrequerido#

Teléfono.

billToEmailstringrequerido#

Correo del comprador.

shipToFirstNamestring#

Nombre.

shipToLastNamestring#

Apellidos.

shipToAddressstring#

Dirección.

shipToAddress2string#

Dirección 2.

shipToCitystring#

Ciudad.

shipToStatestring#

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

shipToZipPostCodestring#

Código postal.

shipToCountrystring#

País en código ISO Alpha-2, por ejemplo CR (Costa Rica), US (EE. UU.) o GT (Guatemala).

shipToTelephonestring#

Teléfono.

subscriptionstringrequerido#

1 para forzar que el cliente guarde la tarjeta en Tilopay, 0 para no.

platformstringrequerido#

Nombre de la plataforma donde se genera la transacción.

returnDatastring#

Valor que Tilopay devuelve en la respuesta final. Se recomienda enviar un string en base 64.

hashVersionstring#

Solo se usa al implementar la verificación de hash. Valores posibles [V1, V2]; por defecto V1.

token_versionstring#

Enviar como valor "v2".

Ejemplo de request#

Los valores <...> son marcadores: reemplazalos por tus credenciales y datos.

{
  "redirect": "https://www.urlToRedirect.com",
  "key": "<api_key>",
  "amount": "1.00",
  "currency": "USD",
  "orderNumber": "1212122",
  "capture": "1",
  "billToFirstName": "DEMO",
  "billToLastName": "DEMO",
  "billToAddress": "San Jose",
  "billToAddress2": "Catedral",
  "billToCity": "JS",
  "billToState": "SJ",
  "billToZipPostCode": "10061",
  "billToCountry": "CR",
  "billToTelephone": "88888888",
  "billToEmail": "cliente@ejemplo.com",
  "shipToFirstName": "DEMO",
  "shipToLastName": "DEMO",
  "shipToAddress": "San Jose",
  "shipToAddress2": "Catedral",
  "shipToCity": "JS",
  "shipToState": "SJ",
  "shipToZipPostCode": "10061",
  "shipToCountry": "CR",
  "shipToTelephone": "88888888",
  "subscription": "0",
  "platform": "api",
  "returnData": "dXNlcl9pZD0xMg==",
  "hashVersion": "V2",
  "token_version": "v2"
}

Respuesta#

{
  "type": "100",
  "html": "Use url redirect",
  "url": "https://secure.tilopay.com/htmls/1212122_574572148file.html"
}

"type": "100" significa que se generó la URL del formulario: redirigí al cliente a url para que complete el pago.

Parámetros que llegan al redirect#

Cuando el cliente termina el pago, Tilopay lo redirige a tu redirect con estos parámetros en la URL:

Parámetro	Qué es
`code`	`1` = transacción aprobada; cualquier otro valor = rechazada
`description`	Texto del resultado
`auth`	Código de autorización
`order`	El `orderNumber` que enviaste
`tpt` y `tilopay-transaction`	Id de la transacción en Tilopay
`OrderHash`	Hash único de la transacción
`returnData`	El valor que enviaste en el request

Antes de entregar el producto o liberar el servicio, confirmá el estado de la transacción con POST /api/v1/consult desde tu servidor — ver consult.

Respuestas de error#

HTTP 300:

{
  "type": "300",
  "message": "Message error"
}

HTTP 400:

{
  "type": "400",
  "message": "Message error"
}

HTTP 402:

{
  "type": "402",
  "message": "Message error"
}

HTTP 403:

{
  "type": "403",
  "message": "Message error"
}

Para interpretar una respuesta que no es de éxito, ver cómo leer una respuesta de error.

Última verificación: 2026-10-20

Ver como Markdown crudo