# API · processPayment

> Parámetros, ejemplo de request y respuesta de processPayment, la operación que abre el formulario de pago.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/hosted-payment-page/process-payment

```http
POST /api/v1/processPayment
```

## Qué hace [#que-hace]

Devuelve la URL del formulario de pago para una compra.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="process-payment-parametro-redirect" name="redirect" type="string" required>
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: para usarlo del lado del comercio hay que escribir a `sac@tilopay.com` y pedir las instrucciones.
</Param>

<Param id="process-payment-parametro-key" name="key" type="string" required>
Llave relacionada con el cliente. Se obtiene en Admin · Tilopay Checkout.
</Param>

<Param id="process-payment-parametro-amount" name="amount" type="string" required>
Monto de la compra.
</Param>

<Param id="process-payment-parametro-currency" name="currency" type="string" required>
Moneda de la compra en formato ISO, por ejemplo USD, CRC, GTQ.
</Param>

<Param id="process-payment-parametro-ordernumber" name="orderNumber" type="string" required>
Número de orden, puede ser alfanumérico.
</Param>

<Param id="process-payment-parametro-capture" name="capture" type="string" required>
Captura y autoriza: 1 sí, 0 no.
</Param>

<Param id="process-payment-parametro-billtofirstname" name="billToFirstName" type="string" required>
Nombre.
</Param>

<Param id="process-payment-parametro-billtolastname" name="billToLastName" type="string" required>
Apellidos.
</Param>

<Param id="process-payment-parametro-billtoaddress" name="billToAddress" type="string" required>
Dirección.
</Param>

<Param id="process-payment-parametro-billtoaddress2" name="billToAddress2" type="string" required>
Dirección 2.
</Param>

<Param id="process-payment-parametro-billtocity" name="billToCity" type="string" required>
Ciudad.
</Param>

<Param id="process-payment-parametro-billtostate" name="billToState" type="string" required>
Estado en formato ISO, por ejemplo CR-SJ (San José, Costa Rica) o US-CA (California, EE. UU.).
</Param>

<Param id="process-payment-parametro-billtozippostcode" name="billToZipPostCode" type="string" required>
Código postal.
</Param>

<Param id="process-payment-parametro-billtocountry" name="billToCountry" type="string" required>
País en código ISO Alpha-2, por ejemplo CR (Costa Rica), US (EE. UU.) o GT (Guatemala).
</Param>

<Param id="process-payment-parametro-billtotelephone" name="billToTelephone" type="string" required>
Teléfono.
</Param>

<Param id="process-payment-parametro-billtoemail" name="billToEmail" type="string" required>
Correo del comprador.
</Param>

<Param id="process-payment-parametro-shiptofirstname" name="shipToFirstName" type="string" required>
Nombre.
</Param>

<Param id="process-payment-parametro-shiptolastname" name="shipToLastName" type="string" required>
Apellidos.
</Param>

<Param id="process-payment-parametro-shiptoaddress" name="shipToAddress" type="string" required>
Dirección.
</Param>

<Param id="process-payment-parametro-shiptoaddress2" name="shipToAddress2" type="string" required>
Dirección 2.
</Param>

<Param id="process-payment-parametro-shiptocity" name="shipToCity" type="string" required>
Ciudad.
</Param>

<Param id="process-payment-parametro-shiptostate" name="shipToState" type="string" required>
Estado en formato ISO, por ejemplo CR-SJ (San José, Costa Rica) o US-CA (California, EE. UU.).
</Param>

<Param id="process-payment-parametro-shiptozippostcode" name="shipToZipPostCode" type="string" required>
Código postal.
</Param>

<Param id="process-payment-parametro-shiptocountry" name="shipToCountry" type="string" required>
País en código ISO Alpha-2, por ejemplo CR (Costa Rica), US (EE. UU.) o GT (Guatemala).
</Param>

<Param id="process-payment-parametro-shiptotelephone" name="shipToTelephone" type="string" required>
Teléfono.
</Param>

<Param id="process-payment-parametro-subscription" name="subscription" type="string" required>
1 para forzar que el cliente guarde la tarjeta en Tilopay, 0 para no.
</Param>

<Param id="process-payment-parametro-platform" name="platform" type="string" required>
Nombre de la plataforma donde se genera la transacción.
</Param>

<Param id="process-payment-parametro-returndata" name="returnData" type="string">
Valor que Tilopay devuelve en la respuesta final. Se recomienda enviar un string en base 64.
</Param>

<Param id="process-payment-parametro-hashversion" name="hashVersion" type="string">
Solo se usa al implementar la verificación de hash. Valores posibles [V1, V2]; por defecto V1.
</Param>

<Param id="process-payment-parametro-token-version" name="token_version" type="string">
Enviar como valor "v2".
</Param>

## Ejemplo de request [#request]

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

```json
{
  "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 [#respuesta]

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

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).