# API · Server-to-server

> A service exclusive to PCI-certified merchants. The URL is provisioned per merchant: it is not self-serve.

- kind: guide
- status: stable
- api_version: v1
- last_verified: 2026-10-20
- url: https://tilopay.com/en/developers/server-to-server

> **Warning:** Restricted access. This is not a self-serve path. You cannot start this integration on your own
> today: it requires merchant PCI certification and a URL provisioned individually by Tilopay.

## What it is [#que-es]

The path where card data passes through your server, which then sends it to the Tilopay
API.

## Who it is for [#para-quien]

- It is a **service exclusive to merchants holding PCI certification**.
- The **URL is customized per merchant**, with its own key. **It is not a public URL.**

That is why the examples on this page carry no real URL: the `Host` and the proxy key are delivered
to each approved merchant.

## Requirements [#requisitos]

1. Valid PCI certification for your company.
2. An active Tilopay account.
3. An approved request, with the URL and key provisioned by Tilopay for your merchant.

## How to request it [#solicitud]

Write to `soporte@tilopay.com` with your business name and the status of your PCI certification. The URL
and key are delivered directly to the approved merchant.

## Request reference [#referencia]

> **Warning:** The `Host` and the `tx-proxy-key` header are delivered by Tilopay to each approved merchant. There is
> no public URL: the examples use placeholders.

```http
POST / HTTP/1.1
Host: url provided by tilopay
```

### Headers [#encabezados]

<Param id="s2s-header-authorization" name="Authorization" type="string">
`bearer {API token}` — see [authentication](/en/developers/api/autenticacion).
</Param>

<Param id="s2s-header-tx-proxy-key" name="tx-proxy-key" type="string">
Transaction proxy key, provided by Tilopay.
</Param>

### Parameters [#parametros]

<Param id="s2s-parametro-key" name="key" type="string">
Key tied to the merchant (required).
</Param>

<Param id="s2s-parametro-card" name="card" type="string">
Card number (required).
</Param>

<Param id="s2s-parametro-cvv" name="cvv" type="string">
Security code (required).
</Param>

<Param id="s2s-parametro-expire" name="expire" type="string">
Expiration date in monthYear format, for example `1023` (required).
</Param>

<Param id="s2s-parametro-name" name="name" type="string">
Cardholder first name (required).
</Param>

<Param id="s2s-parametro-lastname" name="lastname" type="string">
Cardholder last name (required).
</Param>

<Param id="s2s-parametro-phone" name="phone" type="string">
Customer phone (required).
</Param>

<Param id="s2s-parametro-email" name="email" type="string">
Customer email (required).
</Param>

<Param id="s2s-parametro-address" name="address" type="string">
Customer address (required).
</Param>

<Param id="s2s-parametro-city" name="city" type="string">
Customer city (required).
</Param>

<Param id="s2s-parametro-state" name="state" type="string">
State in ISO format, for example `CR-SJ` (San José, Costa Rica) or `US-CA` (California, USA) (required).
</Param>

<Param id="s2s-parametro-zipcode" name="zipcode" type="string">
Postal code (required).
</Param>

<Param id="s2s-parametro-country" name="country" type="string">
Country as ISO Alpha-2 code, for example `CR`, `US`, `GT` (required).
</Param>

<Param id="s2s-parametro-amount" name="amount" type="string">
Purchase amount (required).
</Param>

<Param id="s2s-parametro-currency" name="currency" type="string">
Currency in ISO format, for example `USD`, `CRC`, `GTQ` (required).
</Param>

<Param id="s2s-parametro-ordernumber" name="orderNumber" type="string">
Order number (required).
</Param>

<Param id="s2s-parametro-capture" name="capture" type="number">
`1` captures and authorizes, `0` only authorizes (required).
</Param>

<Param id="s2s-parametro-redirect" name="redirect" type="string">
Response URL (required).
</Param>

Optional shipping data: `shipToFirstName`, `shipToLastName`, `shipToAddress`,
`shipToAddress2`, `shipToCity`, `shipToState`, `shipToZipPostCode`, `shipToCountry`,
`shipToTelephone`.

### Request [#peticion]

```json
{
  "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"
}
```

The collection includes two examples, **with 3DS** and **without 3DS**, sharing the same request body.

### Response [#respuesta]

Without 3DS:

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

With 3DS:

```json
{
  "code": "",
  "description": "",
  "auth": "",
  "orderNumber": "12457",
  "urlRedirect": "https://secure.tilopay.com/htmls/1026345966.html",
  "error": ""
}
```

When the transaction requires 3DS authentication, the response carries the URL in `urlRedirect`; that
is where the cardholder is sent. To interpret `code`, `description` and `error`, see
[response conventions](/en/developers/api/convenciones) and
[how to read an error response](/en/developers/api/procesos-operativos/errors).

## Alternatives without PCI certification [#alternativas]

If you do not hold PCI certification, these paths avoid that scope entirely:

- [Hosted payment page](/en/developers/hosted-payment-page) — Tilopay hosts the form.
- [JavaScript SDK](/en/developers/sdk) — the form lives on your page, but the data travels from the
  browser straight to Tilopay.
- [No code](/en/developers/sin-codigo) — a plugin or an already-integrated platform.