API · processPayment
API v1POST /api/v1/processPaymentWhat it does#
Returns the URL of the payment form for a purchase.
Authentication#
Requires the API bearer token in the Authorization header — see authentication.
Parameters#
Site where you wait for the transaction response, for example mywebsite.com. It must support the GET method. Example response to the 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. When code = 1 the transaction is approved; anything else is declined. OrderHash is a unique string per transaction: its algorithm is not public and is requested by writing to soporte@tilopay.com.
Key associated with the customer. Obtained in Admin panel · Platform integrations.
Purchase amount.
Purchase currency in ISO format, for example USD, CRC, GTQ.
Order number, it can be alphanumeric.
Capture and authorize: 1 yes, 0 no.
First name.
Last names.
Address.
Address 2.
City.
State in ISO format, for example CR-SJ (San José, Costa Rica) or US-CA (California, USA).
Post code.
Country in ISO Alpha-2 code, for example CR (Costa Rica), US (USA) or GT (Guatemala).
Telephone.
Buyer email.
First name.
Last names.
Address.
Address 2.
City.
State in ISO format, for example CR-SJ (San José, Costa Rica) or US-CA (California, USA).
Post code.
Country in ISO Alpha-2 code, for example CR (Costa Rica), US (USA) or GT (Guatemala).
Telephone.
1 to force the customer to save the card in Tilopay, 0 not to.
Name of the platform where the transaction is generated.
Value that Tilopay returns in the final response. Sending a base 64 string is recommended.
Only used when implementing hash verification. Possible values [V1, V2]; V1 by default.
Send as value "v2".
Request example#
The <...> values are placeholders: replace them with your own credentials and data.
{
"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"
}Response#
{
"type": "100",
"html": "Use url redirect",
"url": "https://secure.tilopay.com/htmls/1212122_574572148file.html"
}"type": "100" means the form URL was generated: redirect the customer to url so they can
complete the payment.
Parameters that arrive at the redirect#
When the customer finishes the payment, Tilopay redirects them to your redirect with these
parameters in the URL:
| Parameter | What it is |
|---|---|
code | 1 = transaction approved; any other value = declined |
description | Result text |
auth | Authorization code |
order | The orderNumber you sent |
tpt and tilopay-transaction | Transaction id in Tilopay |
OrderHash | Unique hash of the transaction |
returnData | The value you sent in the request |
Before delivering the product or releasing the service, confirm the transaction status with
POST /api/v1/consult from your server — see consult.
Error responses#
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"
}To interpret a response that is not a success, see how to read an error response.
Last verified: 2026-10-20