API · Server-to-server

API v1

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#

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

Who it is for#

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#

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

How to request it#

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

Request reference#

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.

POST / HTTP/1.1
Host: url provided by tilopay

Headers#

Authorizationstring#

bearer {API token} — see authentication.

tx-proxy-keystring#

Transaction proxy key, provided by Tilopay.

Parameters#

keystring#

Key tied to the merchant (required).

cardstring#

Card number (required).

cvvstring#

Security code (required).

expirestring#

Expiration date in monthYear format, for example 1023 (required).

namestring#

Cardholder first name (required).

lastnamestring#

Cardholder last name (required).

phonestring#

Customer phone (required).

emailstring#

Customer email (required).

addressstring#

Customer address (required).

citystring#

Customer city (required).

statestring#

State in ISO format, for example CR-SJ (San José, Costa Rica) or US-CA (California, USA) (required).

zipcodestring#

Postal code (required).

countrystring#

Country as ISO Alpha-2 code, for example CR, US, GT (required).

amountstring#

Purchase amount (required).

currencystring#

Currency in ISO format, for example USD, CRC, GTQ (required).

orderNumberstring#

Order number (required).

capturenumber#

1 captures and authorizes, 0 only authorizes (required).

redirectstring#

Response URL (required).

The shipTo* fields (shipToFirstName, shipToLastName, shipToAddress, shipToAddress2, shipToCity, shipToState, shipToZipPostCode, shipToCountry, shipToTelephone) appear in the collection examples as shipping data.

Request#

{
  "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#

{
  "code": "1",
  "description": "Transaccion aprobada",
  "auth": "123456",
  "orderNumber": "12345",
  "urlRedirect": "",
  "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 and how to read an error response.

Alternatives without PCI certification#

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

Hosted payment page — Tilopay hosts the form.
JavaScript SDK — the form lives on your page, but the data travels from the browser straight to Tilopay.
No code — a plugin or an already-integrated platform.

Last verified: 2026-08-28 · Owner: equipo-integraciones

View as raw Markdown