{ "openapi": "3.1.0", "info": { "title": "Tilopay API", "version": "v1", "summary": "Server-to-server API of the Tilopay payment gateway.", "description": "Payments, payment links, card tokenization and recurring billing for Central America, the Caribbean and Latin America.\n\nGenerated from the Tilopay Developer Portal reference pages. Every operation links back to its reference page under `externalDocs`.\n\n**Environments.** There is no separate sandbox host: the API and the SDK live on a single host and the mode is switched from the merchant account in the Tilopay portal.\n\n**Authentication.** Call `POST /api/v1/login` to obtain a bearer token and send it in the `Authorization` header of every other call. `POST /api/v1/loginSdk` returns the token passed to `Tilopay.Init()` in the browser SDK.\n\n**Errors.** A non-successful response carries the outcome in the body rather than in the HTTP status. See the error reference page.", "contact": { "name": "Tilopay support", "email": "sac@tilopay.com", "url": "https://www.tilopay.com/developers" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-Tilopay" } }, "externalDocs": { "description": "Tilopay Developer Portal", "url": "https://www.tilopay.com/developers" }, "servers": [ { "url": "https://app.tilopay.com", "description": "Single host for production and test mode." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "Obtain the API token and the SDK token." }, { "name": "Hosted payment page", "description": "Create a transaction and receive a payment URL." }, { "name": "Tokenization", "description": "Store cards in the merchant's private vault." }, { "name": "Recurring - Plans", "description": "Create and manage recurring billing plans." }, { "name": "Recurring - Subscribers", "description": "Manage the subscribers of a plan." }, { "name": "Recurring - Coupons", "description": "Discount coupons for recurring plans." }, { "name": "Recurring - Payments", "description": "Charge a card already stored for a plan." }, { "name": "Payment links", "description": "Create, query and delete payment links." }, { "name": "Operations", "description": "Query transactions, modify them and split settlements." } ], "paths": { "/api/v1/login": { "post": { "operationId": "login", "summary": "Get the API token", "tags": [ "Authentication" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/autenticacion/token-api" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apiuser": { "type": "string", "description": "Merchant API user, obtained in Admin - Tilopay Checkout." }, "password": { "type": "string", "description": "Merchant API password, obtained in Admin - Tilopay Checkout." } } }, "example": { "apiuser": "", "password": "" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" } } }, "example": { "access_token": "", "token_type": "bearer", "expires_in": 86400 } } } } }, "security": [] } }, "/api/v1/loginSdk": { "post": { "operationId": "loginSdk", "summary": "Get the SDK token", "tags": [ "Authentication" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/autenticacion/token-sdk" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apiuser": { "type": "string", "description": "Merchant API user." }, "password": { "type": "string", "description": "Merchant API password." }, "key": { "type": "string", "description": "Merchant API key." } } }, "example": { "apiuser": "", "password": "", "key": "" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "string" } } }, "example": { "access_token": "351d477adaaa51cdbb33ae4b4b8c843aa759f131c1c38415180b5035543d59d2f23f4e049706f5fa71c5f0d9ff763960a3cd035b4c1cefa428c90bedb672f780", "token_type": "bearer", "expires_in": "2023-06-05 13:32:06" } } } } }, "security": [] } }, "/api/v1/processPayment": { "post": { "operationId": "processPayment", "summary": "Create a hosted payment page transaction", "tags": [ "Hosted payment page" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/hosted-payment-page/process-payment" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect": { "type": "string", "description": "Site where you expect the transaction response, for example `mywebsite.com`. It must support the GET method. Example redirect response: `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`. If `code = 1` the transaction is approved; in any other case it is declined. `OrderHash` is a unique string per transaction: to use it on the merchant side, write to sac@tilopay.com and request the instructions." }, "key": { "type": "string", "description": "Key associated with the customer. Obtained in Admin - Tilopay Checkout." }, "amount": { "type": "string", "description": "Purchase amount." }, "currency": { "type": "string", "description": "Purchase currency in ISO format, for example USD, CRC, GTQ." }, "orderNumber": { "type": "string", "description": "Order number; it may be alphanumeric." }, "capture": { "type": "string", "description": "Capture and authorize: 1 yes, 0 no." }, "billToFirstName": { "type": "string", "description": "First name." }, "billToLastName": { "type": "string", "description": "Last name." }, "billToAddress": { "type": "string", "description": "Address." }, "billToAddress2": { "type": "string", "description": "Address line 2." }, "billToCity": { "type": "string", "description": "City." }, "billToState": { "type": "string", "description": "State in ISO format, for example CR-SJ (San Jose, Costa Rica) or US-CA (California, USA)." }, "billToZipPostCode": { "type": "string", "description": "Postal code." }, "billToCountry": { "type": "string", "description": "Country in ISO Alpha-2 code, for example CR (Costa Rica), US (USA) or GT (Guatemala)." }, "billToTelephone": { "type": "string", "description": "Phone number." }, "billToEmail": { "type": "string", "description": "Buyer email." }, "shipToFirstName": { "type": "string", "description": "First name." }, "shipToLastName": { "type": "string", "description": "Last name." }, "shipToAddress": { "type": "string", "description": "Address." }, "shipToAddress2": { "type": "string", "description": "Address line 2." }, "shipToCity": { "type": "string", "description": "City." }, "shipToState": { "type": "string", "description": "State in ISO format, for example CR-SJ (San Jose, Costa Rica) or US-CA (California, USA)." }, "shipToZipPostCode": { "type": "string", "description": "Postal code." }, "shipToCountry": { "type": "string", "description": "Country in ISO Alpha-2 code, for example CR (Costa Rica), US (USA) or GT (Guatemala)." }, "shipToTelephone": { "type": "string", "description": "Phone number." }, "subscription": { "type": "string", "description": "Set to 1 to force the customer to save the card in Tilopay, 0 otherwise." }, "platform": { "type": "string", "description": "Name of the platform where the transaction originates." }, "returnData": { "type": "string", "description": "Value Tilopay returns in the final response. Sending a base64 string is recommended." }, "hashVersion": { "type": "string", "description": "Used only when implementing hash verification. Possible values [V1, V2]; defaults to V1." }, "token_version": { "type": "string", "description": "Send the literal value \"v2\"." } }, "required": [ "amount", "billToAddress", "billToAddress2", "billToCity", "billToCountry", "billToEmail", "billToFirstName", "billToLastName", "billToState", "billToTelephone", "billToZipPostCode", "capture", "currency", "key", "orderNumber", "platform", "redirect", "shipToAddress", "shipToAddress2", "shipToCity", "shipToCountry", "shipToFirstName", "shipToLastName", "shipToState", "shipToTelephone", "shipToZipPostCode", "subscription" ] }, "example": { "redirect": "https://www.urlToRedirect.com", "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" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "html": { "type": "string" }, "url": { "type": "string" } } }, "example": { "type": "100", "html": "Use url redirect", "url": "https://secure.tilopay.com/htmls/1212122_574572148file.html" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/consult": { "post": { "operationId": "consult", "summary": "Get a transaction by order number", "tags": [ "Operations" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/procesos-operativos/consult" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "orderNumber": { "type": "string", "description": "Order number queried." }, "merchantId": { "type": "string", "description": "Merchant id." } } }, "example": { "key": "", "orderNumber": "1212122", "merchantId": "" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "response": { "type": "array", "items": { "type": "object", "properties": { "id_tilopay": { "type": "integer" }, "orderNumber": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "merchantId": { "type": "string" }, "code": { "type": "string" }, "response": { "type": "string" }, "auth": { "type": "string" }, "commission": { "type": "number" }, "iva_commission": { "type": "number" }, "retention_iva": { "type": "number" }, "retention_rent": { "type": "number" }, "cost": { "type": "number" }, "cost_iva": { "type": "number" }, "net_to_liquidate": { "type": "string" }, "capture": { "type": "string" }, "card": { "type": "string" }, "last": { "type": "string" }, "environment": { "type": "string" }, "type": { "type": "string" }, "date": { "type": "string" } } } } } }, "example": { "type": "200", "message": "", "response": [ { "id_tilopay": 734312, "orderNumber": "1212122", "amount": "5.00", "currency": "USD", "merchantId": "88803956", "code": "1", "response": "Transacción aprobada", "auth": "123456", "commission": 0.18, "iva_commission": 0.02, "retention_iva": 0.27, "retention_rent": 0.09, "cost": 0.35, "cost_iva": 0.05, "net_to_liquidate": "4.04", "capture": "Capture", "card": "4021", "last": "5221", "environment": "Test", "type": "Payment", "date": "2024-07-31 16:59:20" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/consultTransactions": { "post": { "operationId": "consultTransactions", "summary": "List transactions in a date range", "tags": [ "Operations" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/procesos-operativos/consult-transactions" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "startDate": { "type": "string", "description": "Start date, `Y-m-d H:i:s` format - for example \"2022-01-15 00:00:00\"." }, "endDate": { "type": "string", "description": "End date, `Y-m-d H:i:s` format - for example \"2022-08-01 23:59:59\"." }, "onlyAproved": { "type": "integer", "description": "Whether to retrieve approved transactions only. 0 = any, 1 = approved only." }, "environment": { "type": "integer", "description": "Environment of the transactions to retrieve. 0 = production, 1 = test." }, "currency": { "type": "array", "items": {}, "description": "Array of currencies to retrieve, for example [\"USD\", \"CRC\"]." }, "merchantId": { "type": "string", "description": "Merchant id." }, "orderNumber": { "type": "string", "description": "Order number." }, "email": { "type": "string", "description": "Customer email." }, "auth": { "type": "string", "description": "Authorization number." } }, "required": [ "endDate", "key", "startDate" ] }, "example": { "key": "", "startDate": "2023-06-01 00:00:00", "endDate": "2023-06-30 23:59:59", "onlyAproved": 1, "environment": 1, "currency": [ "USD", "CRC" ], "merchantId": "", "orderNumber": "12135", "email": "customer@example.com", "auth": "123456" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "response": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "orderNumber": { "type": "string" }, "amount": { "type": "string" }, "taxes": { "type": "string" }, "discount": { "type": "string" }, "discount_name": { "type": "string" }, "currency": { "type": "string" }, "merchantId": { "type": "string" }, "code": { "type": "string" }, "response": { "type": "string" }, "auth": { "type": "string" }, "card": { "type": "string" }, "last": { "type": "string" }, "email": { "type": "string" }, "commission": { "type": "number" }, "iva_commission": { "type": "number" }, "retention_iva": { "type": "number" }, "retention_rent": { "type": "number" }, "cost": { "type": "number" }, "cost_iva": { "type": "number" }, "net_to_liquidate": { "type": "number" }, "capture": { "type": "string" }, "type": { "type": "string" }, "environment": { "type": "string" }, "date": { "type": "string" } } } } } }, "example": { "type": "200", "message": "", "response": [ { "id": 734329, "orderNumber": "12135", "amount": "5.00", "taxes": "0.00", "discount": "0.00", "discount_name": "", "currency": "USD", "merchantId": "", "code": "1", "response": "Transacción aprobada", "auth": "123456", "card": "4021", "last": "5221", "email": "customer@example.com", "commission": 0.18, "iva_commission": 0.02, "retention_iva": 0.27, "retention_rent": 0.09, "cost": 0.35, "cost_iva": 0.05, "net_to_liquidate": 4.04, "capture": "Capture", "type": "Payment", "environment": "Production", "date": "2024-07-31 16:59:20" }, { "id": 734330, "orderNumber": "12136", "amount": "5.00", "taxes": "0.00", "discount": "0.00", "discount_name": "", "currency": "USD", "merchantId": "", "code": "1", "response": "Transacción aprobada", "auth": "123456", "card": "4021", "last": "5221", "email": "customer@example.com", "commission": 0.18, "iva_commission": 0.02, "retention_iva": 0.27, "retention_rent": 0.09, "cost": 0.35, "cost_iva": 0.05, "net_to_liquidate": 4.04, "capture": "Capture", "type": "Payment", "environment": "Production", "date": "2024-07-31 17:25:35" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/orders/liquidation/split": { "post": { "operationId": "split", "summary": "Split the settlement of an approved order", "tags": [ "Operations" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/procesos-operativos/split" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Id of the approved order in Tilopay." }, "commerces": { "type": "array", "items": {}, "description": "Associative array with the `email` and `amount` keys of each merchant the settlement is split with. Including the owning merchant is optional: if its amount is not specified it receives the remainder of the split, and if it is included and there is a remainder, the remainder is added to it." }, "lang": { "type": "string", "description": "Request language." } } }, "example": { "order_id": "1", "commerces": [ { "email": "commerce-1@example.com", "amount": "7.5" }, { "email": "commerce-2@example.com", "amount": "5.5" } ], "lang": "en" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "description": { "type": "string" }, "response": { "type": "object", "properties": { "total_order_splitted": { "type": "integer" }, "order_id": { "type": "integer" }, "order_number": { "type": "string" }, "order_key": { "type": "string" }, "order_currency": { "type": "string" }, "order_amount": { "type": "string" }, "splitted_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "amount": { "type": "integer" }, "commerce_name": { "type": "string" }, "commerce_email": { "type": "string" } } } } } } } }, "example": { "type": "200", "message": "Great", "description": "Order splitted successfully", "response": { "total_order_splitted": 3, "order_id": 1, "order_number": "PFC000069-TYP785237_313", "order_key": "", "order_currency": "USD", "order_amount": "33.00", "splitted_orders": [ { "id": 1, "amount": 20, "commerce_name": "Commerce owner name", "commerce_email": "owner@example.com" }, { "id": 2, "amount": 7.5, "commerce_name": "Commerce name", "commerce_email": "commerce-1@example.com" }, { "id": 3, "amount": 5.5, "commerce_name": "Commerce name", "commerce_email": "commerce-2@example.com" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/processModification": { "post": { "operationId": "processModification", "summary": "Capture, refund or reverse a transaction", "tags": [ "Operations" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/procesos-operativos/process-modification" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderNumber": { "type": "string", "description": "Example: `1214352`" }, "type": { "type": "string", "description": "Example: `2`" }, "amount": { "type": "string", "description": "Example: `1.00`" }, "key": { "type": "string", "description": "Key associated with the customer. Obtained in Admin - Tilopay Checkout." } } }, "example": { "orderNumber": "1214352", "type": "2", "amount": "1.00", "key": "" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "transactionId": { "type": "string" }, "ReasonCode": { "type": "string" }, "ReasonCodeDescription": { "type": "string" }, "OrderHash": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/createLinkPayment": { "post": { "operationId": "createLinkPayment", "summary": "Create a payment link", "tags": [ "Payment links" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/links-de-pago/create-link-payment" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "amount": { "type": "string", "description": "Amount of the payment link." }, "currency": { "type": "string", "description": "Currency code in ISO 4217 format." }, "reference": { "type": "string", "description": "Payment link reference." }, "type": { "type": "integer", "description": "Link type: 0 unlimited, 1 single use." }, "description": { "type": "string", "description": "Payment description." }, "client": { "type": "string", "description": "Customer name; applies only when type is 1." }, "callback_url": { "type": "string", "description": "Optional. URL, called with GET, the customer is redirected to with the response once the payment completes. Example payload: `code=Val&description=Val&auth=Val&tilopayLinkId=Val&orderNumber=Val&tilopayOrderId=Val&creditCardToken=Val&creditCardBrand=Val&last4CreditCardNumber=Val&orderHash=Val`" }, "webhook_url": { "type": "string", "description": "Optional. URL that receives the response webhook when the payment completes. It must accept POST in order to receive the data. Example payload: `{\"code\": \"1\", \"codeDescription\": \"Aprobada\", \"auth\": \"123456\", \"tilopayLinkId\": 54421, \"orderNumber\": \"TPT123\", \"tilopayOrderId\": 12233, \"creditCardToken\": \"41111******11111\", \"creditCardBrand\": \"Visa\", \"last4CreditCardNumber\": \"1111\", \"linkDescription\": \"Payment link description\", \"orderHash\": \"\"}`" } }, "required": [ "amount", "currency", "key" ] }, "example": { "key": "", "amount": "10", "currency": "USD", "reference": "123456", "type": 0, "description": "Description", "client": "Client name", "callback_url": "", "webhook_url": "" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "integer" } } }, "example": { "type": "200", "message": "Success", "url": "https://app.tilopay.com/link/MjMwMjQ=", "id": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/deleteLinkPayment": { "post": { "operationId": "deleteLinkPayment", "summary": "Delete a payment link", "tags": [ "Payment links" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/links-de-pago/delete-link-payment" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Payment link id." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "35" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getDetailLinkPayment/{link_payment_id}/{api_key}": { "get": { "operationId": "getDetailLinkPayment", "summary": "Get a payment link with its payments", "tags": [ "Payment links" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/links-de-pago/detail-link-payment" }, "parameters": [ { "name": "link_payment_id", "in": "path", "required": true, "description": "Id of the payment link to query.", "schema": { "type": "string" } }, { "name": "api_key", "in": "path", "required": true, "description": "Merchant API key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "detail": { "type": "object", "properties": { "id": { "type": "integer" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "reference": { "type": "string" }, "client": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "callback_url": { "type": [ "string", "null" ] }, "create": { "type": "string" } } }, "payments": { "type": "array", "items": {} } } }, "example": { "type": "200", "message": "Success", "detail": { "id": 6201, "amount": "45.00", "currency": "USD", "reference": "Producto de prueba 1 TP-Shop", "client": "NA", "type": "Unlimited", "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "callback_url": null, "create": "2022-10-24 08:45:14" }, "payments": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getLinkPaymentById/{link_payment_id}/{api_key}": { "get": { "operationId": "getLinkPaymentById", "summary": "Get a payment link by id", "tags": [ "Payment links" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/links-de-pago/payment-by-id" }, "parameters": [ { "name": "link_payment_id", "in": "path", "required": true, "description": "Id of the payment link to query.", "schema": { "type": "string" } }, { "name": "api_key", "in": "path", "required": true, "description": "Merchant API key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "reference": { "type": "string" }, "url": { "type": "string" }, "callback_url": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "times_used": { "type": [ "string", "null" ] }, "picture": { "type": "string" }, "create": { "type": "string" }, "payments": { "type": "array", "items": {} } } } } }, "example": { "type": "200", "message": "Success", "data": { "id": 1, "amount": "45.00", "currency": "USD", "reference": "Producto de prueba 1 TP-Shop", "url": "https://admin.tilopay.com/link/loNj8E2MA==", "callback_url": null, "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/51087219_.png", "create": "2022-10-24 08:45:14", "payments": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getLinkPaymentList/{api_key}/{limit}": { "get": { "operationId": "getLinkPaymentList", "summary": "List payment links", "tags": [ "Payment links" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/links-de-pago/payment-item-list" }, "parameters": [ { "name": "api_key", "in": "path", "required": true, "description": "Merchant API key.", "schema": { "type": "string" } }, { "name": "limit", "in": "path", "required": true, "description": "Number of records per page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "current_page": { "type": "integer" }, "first_page_url": { "type": "string" }, "from": { "type": "integer" }, "last_page": { "type": "integer" }, "last_page_url": { "type": "string" }, "next_page_url": { "type": "string" }, "path": { "type": "string" }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": "integer" }, "total": { "type": "integer" }, "payment_link": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "reference": { "type": "string" }, "url": { "type": "string" }, "callback_url": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "times_used": { "type": [ "string", "null" ] }, "picture": { "type": "string" }, "create": { "type": "string" } } } } } } } }, "example": { "type": "200", "message": "Success", "data": { "current_page": 1, "first_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=1", "from": 1, "last_page": 2, "last_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=2", "next_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=2", "path": "http://app.tilopay.com/api/v1/getLinkPaymentList//10", "per_page": 10, "prev_page_url": null, "to": 10, "total": 16, "payment_link": [ { "id": 1, "amount": "45.00", "currency": "USD", "reference": "Producto de prueba 1 TP-Shop", "url": "https://admin.tilopay.com/link/3dNjE2MA3sdd==", "callback_url": null, "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/51087219_.png", "create": "2022-10-24 08:45:14" }, { "id": 2, "amount": "35.00", "currency": "USD", "reference": "Producto de prueba 2", "url": "https://admin.tilopay.com/link/dwNjE2see3MA==", "callback_url": null, "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/64156766_.png", "create": "2022-10-24 08:45:14" }, { "id": 3, "amount": "45.00", "currency": "USD", "reference": "Producto de prueba 3", "url": "https://admin.tilopay.com/link/f4NjE2MwsdA==", "callback_url": null, "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/88435879_.png", "create": "2022-10-24 08:45:14" }, { "id": 4, "amount": "45.00", "currency": "USD", "reference": "test", "url": "https://admin.tilopay.com/link/ceNjE2sxw2MA==", "callback_url": null, "description": "ddd", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png", "create": "2022-10-24 08:45:14" }, { "id": 5, "amount": "45.00", "currency": "USD", "reference": "test", "url": "https://admin.tilopay.com/link/cweNjE2Mfd5A==", "callback_url": null, "description": "ddd", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png", "create": "2022-10-24 08:45:14" }, { "id": 6, "amount": "45.00", "currency": "USD", "reference": "test", "url": "https://admin.tilopay.com/link/ce3NjE2fg5eMA==", "callback_url": null, "description": "ddd", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png", "create": "2022-10-24 08:45:14" }, { "id": 7, "amount": "45.00", "currency": "USD", "reference": "test", "url": "https://admin.tilopay.com/link/dsNjE2MAd32==", "callback_url": null, "description": "ddd", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png", "create": "2022-10-24 08:45:14" }, { "id": 8, "amount": "45.00", "currency": "USD", "reference": "test", "url": "https://admin.tilopay.com/link/NjE2sd32MA==", "callback_url": null, "description": "ddd", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png", "create": "2022-10-24 08:45:14" }, { "id": 9, "amount": "45.00", "currency": "USD", "reference": "test", "url": "https://admin.tilopay.com/link/sd3NjE2MA==", "callback_url": null, "description": "ddd", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png", "create": "2022-10-24 08:45:14" }, { "id": 10, "amount": "45.00", "currency": "USD", "reference": "test", "url": "https://admin.tilopay.com/link/d3dNjE2MA==", "callback_url": null, "description": "ddd", "times_used": null, "picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png", "create": "2022-10-24 08:45:14" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/createCoupon": { "post": { "operationId": "createCoupon", "summary": "Create a coupon", "tags": [ "Recurring - Coupons" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/cupones/create-coupon" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "planId": { "type": "integer", "description": "Recurring plan id." }, "active_users": { "type": "integer", "description": "User permission. 0 = allow new users only, 1 = allow already registered users." }, "type_discount": { "type": "integer", "description": "Discount type. 1 = percentage, 2 = fixed amount." }, "discount": { "type": "integer", "description": "Numeric value of the discount." }, "expire": { "type": "string", "description": "Coupon expiration date, `Y-m-d` format (for example 2025-10-20)." }, "email_group": { "type": "integer", "description": "Email permission. 1 = specific emails, 2 = any email." }, "email": { "type": "string", "description": "Comma-separated list of emails. Required when `email_group` is sent as 1." }, "usage": { "type": "integer", "description": "Total number of uses." }, "renews": { "type": "integer", "description": "Total number of valid renewals." }, "renews_by_user": { "type": "integer", "description": "Total uses by the same user." } }, "required": [ "active_users", "discount", "email_group", "expire", "key", "planId", "type_discount" ] }, "example": { "key": "", "planId": 10, "active_users": 1, "type_discount": 1, "discount": 40, "expire": "2025-10-20", "email_group": 1, "email": "cliente@ejemplo.com, cliente@ejemplo.com", "usage": 1, "renews": 2, "renews_by_user": 2 } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" }, "id": { "type": "integer" }, "code": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success", "id": 10788, "code": "E6RMS339" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/deleteCoupon": { "post": { "operationId": "deleteCoupon", "summary": "Delete a coupon", "tags": [ "Recurring - Coupons" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/cupones/delete-coupon" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Coupon id." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getCoupon": { "post": { "operationId": "getCoupon", "summary": "Get a coupon", "tags": [ "Recurring - Coupons" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/cupones/get-coupon" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Coupon id." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "recurrent_id": { "type": "integer" }, "code": { "type": "string" }, "active_users": { "type": "integer" }, "type_discount": { "type": "integer" }, "discount": { "type": "string" }, "expire": { "type": "string" }, "email_group": { "type": "integer" }, "email": { "type": "string" }, "usage": { "type": "integer" }, "renews": { "type": "integer" }, "renews_by_user": { "type": "integer" }, "usage_counter": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "deleted_at": { "type": [ "string", "null" ] } } } } }, "example": { "type": "200", "message": "Success", "data": { "id": 10788, "recurrent_id": 10, "code": "E6RMS339", "active_users": 1, "type_discount": 1, "discount": "40.00", "expire": "2026-10-20", "email_group": 1, "email": "cliente@ejemplo.com, otro@ejemplo.com", "usage": 1, "renews": 2, "renews_by_user": 2, "usage_counter": 0, "created_at": "2026-09-02T20:12:01.000000Z", "updated_at": "2026-09-02T20:12:01.000000Z", "deleted_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getRepeatCoupons": { "post": { "operationId": "getRepeatCoupons", "summary": "List the coupons of a plan", "tags": [ "Recurring - Coupons" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/cupones/get-coupons" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Recurring plan id." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "active_users": { "type": "integer" }, "type_discount": { "type": "integer" }, "discount": { "type": "string" }, "expire": { "type": "string" }, "email_group": { "type": "integer" }, "email": { "type": [ "string", "null" ] }, "usage": { "type": "integer" }, "renews": { "type": "integer" }, "renews_by_user": { "type": "integer" }, "usage_counter": { "type": "integer" }, "create": { "type": "string" } } } } } }, "example": { "type": "200", "message": "Success", "data": [ { "id": 10787, "code": "TK7DPCHY", "active_users": 1, "type_discount": 1, "discount": "30.00", "expire": "2026-06-12", "email_group": 2, "email": null, "usage": 1, "renews": 1, "renews_by_user": 1, "usage_counter": 0, "create": "2026-06-12 15:17:34" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/processRecurrentPayment": { "post": { "operationId": "processRecurrentPayment", "summary": "Charge a stored card", "tags": [ "Recurring - Payments" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/realizar-pago/process-recurrent-payment" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key associated with the customer. Obtained in Admin - Tilopay Checkout." }, "amount": { "type": "string", "description": "Purchase amount." }, "currency": { "type": "string", "description": "Purchase currency in ISO format, for example USD, CRC, GTQ." }, "orderNumber": { "type": "string", "description": "Order number; it may be alphanumeric." }, "capture": { "type": "string", "description": "Capture and authorize: 1 yes, 0 no." }, "email": { "type": "string", "description": "Cardholder email." }, "card": { "type": "string", "description": "Card token; it must be the v2 token. When implementing hash verification, use the `hashVersion` field, possible values [V1, V2], defaults to V1." } }, "required": [ "amount", "capture", "card", "currency", "email", "key", "orderNumber" ] }, "example": { "key": "", "amount": "10.00", "currency": "USD", "orderNumber": "1213", "capture": "1", "email": "myemail@exapmle.com", "card": "511111_00GOB1111" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "response": { "type": "string" }, "description": { "type": "string" }, "auth": { "type": "string" }, "tpt": { "type": "integer" }, "order_id": { "type": "string" }, "tilopayTransaction": { "type": "integer" }, "orderHash": { "type": "string" } } }, "example": { "type": "200", "response": "1", "description": "Transacción aprobada", "auth": "123456", "tpt": 734329, "order_id": "12135", "tilopayTransaction": 734329, "orderHash": "f3ad85046d249bc7a781eed5285a5ded92045a2e11108063504deec72ec9b338" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/createPlanRepeat": { "post": { "operationId": "createPlanRepeat", "summary": "Create a recurring plan", "tags": [ "Recurring - Plans" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/planes/create-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "title": { "type": "string", "description": "Title of the recurring plan." }, "description": { "type": "string", "description": "Plan description." }, "frecuency": { "type": "integer", "description": "Billing frequency. 1 = daily, 2 = weekly, 3 = monthly, 4 = yearly, 5 = biweekly, 6 = bimonthly, 7 = quarterly, 8 = every four months, 9 = every six months." }, "currency": { "type": "string", "description": "Currency code in ISO 4217 format." }, "first_amount": { "type": "integer", "description": "Amount of the initial payment." }, "trial": { "type": "integer", "description": "Enables the free trial period: 0 no, 1 yes." }, "trial_days": { "type": "integer", "description": "Number of days in the free trial period." }, "attempts": { "type": "integer", "description": "Number of retries for failed charges." }, "modality": { "type": "array", "items": {}, "description": "Array of plan modalities." }, "thanks_url": { "type": "string", "description": "Optional. Merchant's own thank-you URL; it must support the GET method." }, "webhook_subscribe": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when a customer subscribes successfully. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'modality': 'ModalityName', 'amount': 25, 'frequency': '', 'coupon': '5HT5W8YT', 'free_trial': 1, 'next_payment_date': '2023-02-25'}`" }, "webhook_payment": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when the customer is charged successfully. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'amount': 25, 'auth': '123456', 'orderNumber': 'PRE123456'}`" }, "webhook_rejected": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when a payment fails. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'amount': 25}`" }, "webhook_unsubscribe": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when a customer cancels the subscription to one of their plans. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'expire': '2023-02-25'}`" }, "webhook_reactive": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when a customer reactivates the subscription to one of their plans. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'next_payment_date': '2023-02-25'}`" }, "end_at": { "type": "string", "description": "End date of the recurring plan, `d-m-Y` format (for example 25-09-2022). Send it empty if the plan has no end date." }, "notify": { "type": "integer", "description": "Set to 1 to append the `notify_detail` and `notify_note` text to the notification email. Set to 0 to append neither." }, "notify_detail_es": { "type": "string", "description": "Detail text in Spanish. Optional when `notify` is 0." }, "notify_detail_en": { "type": "string", "description": "Detail text in English. Optional when `notify` is 0." }, "notify_note_es": { "type": "string", "description": "Notes text in Spanish. Optional when `notify` is 0." }, "notify_note_en": { "type": "string", "description": "Notes text in English. Optional when `notify` is 0." } }, "required": [ "attempts", "currency", "first_amount", "key", "modality", "title", "trial", "trial_days" ] }, "example": { "key": "", "title": "Plan title", "description": "Plan description", "frecuency": 1, "currency": "USD", "first_amount": 0, "trial": 0, "trial_days": 0, "attempts": 1, "modality": [ { "title": "Basic", "amount": 10 }, { "title": "Premium", "amount": 30 } ], "thanks_url": "", "webhook_subscribe": "", "webhook_payment": "", "webhook_rejected": "", "webhook_unsubscribe": "", "webhook_reactive": "", "end_at": "25-10-2023", "notify": 0, "notify_detail_es": "", "notify_detail_en": "", "notify_note_es": "", "notify_note_en": "" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" }, "id": { "type": "integer" }, "url": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success", "id": 624, "url": "https://app.tilopay.com/link/TmpJMHwx" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/deletePlanRepeat": { "post": { "operationId": "deletePlanRepeat", "summary": "Delete a recurring plan", "tags": [ "Recurring - Plans" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/planes/delete-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Recurring plan id." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "625" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/editPlanRepeat": { "post": { "operationId": "editPlanRepeat", "summary": "Edit a recurring plan", "tags": [ "Recurring - Plans" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/planes/edit-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "integer", "description": "Recurring plan id." }, "title": { "type": "string", "description": "Title of the recurring plan." }, "description": { "type": "string", "description": "Plan description." }, "frecuency": { "type": "integer", "description": "Billing frequency. 1 = daily, 2 = weekly, 3 = monthly, 4 = yearly, 5 = biweekly, 6 = bimonthly, 7 = quarterly, 8 = every four months, 9 = every six months." }, "currency": { "type": "string", "description": "Currency code in ISO 4217 format." }, "first_amount": { "type": "integer", "description": "Amount of the initial payment." }, "trial": { "type": "integer", "description": "Enables the free trial period: 0 no, 1 yes." }, "trial_days": { "type": "integer", "description": "Number of days in the free trial period." }, "attempts": { "type": "integer", "description": "Number of retries for failed charges." }, "status": { "type": "integer", "description": "Recurring plan status. 0 = inactive, 1 = active, 2 = active but closed to new registrations." }, "thanks_url": { "type": "string", "description": "Optional. Merchant's own thank-you URL; it must support the GET method." }, "webhook_subscribe": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when a customer subscribes successfully. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'modality': 'ModalityName', 'amount': 25, 'frequency': '', 'coupon': '5HT5W8YT', 'free_trial': 1, 'next_payment_date': '2023-02-25'}`" }, "webhook_payment": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when the customer is charged successfully. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'amount': 25, 'auth': '123456', 'orderNumber': 'PRE123456'}`" }, "webhook_rejected": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when a payment fails. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'amount': 25}`" }, "webhook_unsubscribe": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when a customer cancels the subscription to one of their plans. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'expire': '2023-02-25'}`" }, "webhook_reactive": { "type": "string", "description": "Optional. Webhook URL, called with POST, that receives the callback in the request body when a customer reactivates the subscription to one of their plans. Example payload: `{'id_plan': 1, 'email': 'email@email.com', 'next_payment_date': '2023-02-25'}`" }, "end_at": { "type": "string", "description": "End date of the recurring plan, `d-m-Y` format (for example 25-09-2022). Send it empty if the plan has no end date." } }, "required": [ "attempts", "currency", "first_amount", "id", "key", "status", "title", "trial", "trial_days" ] }, "example": { "key": "", "id": 3, "title": "Plan title", "description": "Plan description", "frecuency": 2, "currency": "USD", "first_amount": 0, "trial": 0, "trial_days": 0, "attempts": 5, "status": 1, "thanks_url": "", "webhook_subscribe": "", "webhook_payment": "", "webhook_rejected": "", "webhook_unsubscribe": "", "webhook_reactive": "", "end_at": "25-10-2023" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" }, "url": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success", "url": "" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getPlanRepeat": { "post": { "operationId": "getPlanRepeat", "summary": "Get a recurring plan", "tags": [ "Recurring - Plans" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/planes/get-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Recurring plan id." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "3" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "frequency": { "type": "integer" }, "currency": { "type": "string" }, "first_amount": { "type": "string" }, "trial": { "type": "integer" }, "trial_days": { "type": "integer" }, "attempts": { "type": "integer" }, "thanks_url": { "type": [ "string", "null" ] }, "webhook_subscribe": { "type": [ "string", "null" ] }, "webhook_payment": { "type": [ "string", "null" ] }, "webhook_rejected": { "type": [ "string", "null" ] }, "webhook_unsubscribe": { "type": [ "string", "null" ] }, "webhook_reactive": { "type": [ "string", "null" ] }, "modality": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "amount": { "type": "string" } } } }, "end_at": { "type": [ "string", "null" ] } } } } }, "example": { "type": "200", "message": "Success", "plan": { "id": 232, "title": "Prueba repeat", "description": "Plan repeat de prueba mensual", "frequency": 3, "currency": "USD", "first_amount": "5.00", "trial": 0, "trial_days": 0, "attempts": 5, "thanks_url": null, "webhook_subscribe": null, "webhook_payment": null, "webhook_rejected": null, "webhook_unsubscribe": null, "webhook_reactive": null, "modality": [ { "id": 292, "title": "Pago mensual prueba repeat modalidad", "amount": "10.00" } ], "end_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getPlansRepeat": { "post": { "operationId": "getPlansRepeat", "summary": "List recurring plans", "tags": [ "Recurring - Plans" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/planes/get-plans" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." } }, "required": [ "key" ] }, "example": { "key": "" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "frequency": { "type": "integer" }, "currency": { "type": "string" }, "first_amount": { "type": "string" }, "trial": { "type": "integer" }, "trial_days": { "type": "integer" }, "attempts": { "type": "integer" }, "status": { "type": "integer" }, "thanks_url": { "type": "string" }, "return_url": { "type": [ "string", "null" ] }, "webhook_subscribe": { "type": "string" }, "webhook_payment": { "type": "string" }, "webhook_rejected": { "type": "string" }, "webhook_unsubscribe": { "type": "string" }, "webhook_reactive": { "type": "string" }, "modality": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "amount": { "type": "string" } } } }, "end_at": { "type": "string" } } } } } }, "example": { "type": "200", "message": "Success", "data": [ { "id": 276, "title": "Plan test 1", "description": "Plan", "frequency": 1, "currency": "USD", "first_amount": "0.00", "trial": 0, "trial_days": 0, "attempts": 1, "status": 1, "thanks_url": "", "return_url": null, "webhook_subscribe": "", "webhook_payment": "", "webhook_rejected": "", "webhook_unsubscribe": "", "webhook_reactive": "", "modality": [ { "id": 131, "title": "Basic", "amount": "10.00" } ], "end_at": "2022-10-25" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/deleteSuscriptorRepeat": { "post": { "operationId": "deleteSuscriptorRepeat", "summary": "Delete a subscriber", "tags": [ "Recurring - Subscribers" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/suscriptores/delete-suscriptor-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id_suscriptor": { "type": "string", "description": "Subscriber id." } }, "required": [ "id_suscriptor", "key" ] }, "example": { "key": "", "id_suscriptor": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/editSuscriptorRepeat": { "post": { "operationId": "editSuscriptorRepeat", "summary": "Edit a subscriber", "tags": [ "Recurring - Subscribers" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/suscriptores/edit-suscriptor-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Subscriber id." }, "status": { "type": "string", "description": "Subscriber status. 1 = active, 3 = paused, 4 = deleted." }, "expire": { "type": "string", "description": "Plan expiration date, `yy-m-d` format." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "2", "status": "2", "expire": "2023-10-25" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getSuscriptorPayments": { "post": { "operationId": "getSuscriptorPayments", "summary": "List the payments of a plan's subscribers", "tags": [ "Recurring - Subscribers" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/suscriptores/suscriptor-payments" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Recurring plan id." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "commerce_id": { "type": "integer" }, "suscriptor_id": { "type": "integer" }, "reference": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "integer" }, "data": { "type": "string" }, "create": { "type": "string" } } } } } }, "example": { "type": "200", "message": "Success", "data": [ { "id": 150, "commerce_id": 37, "suscriptor_id": 86, "reference": "0", "currency": "USD", "amount": "0.00", "status": 0, "data": "{\"first\":1,\"expire\":\"2024-12-28T19:05:29.572648Z\",\"amount\":0,\"activeAmount\":0,\"originalAmount\":0,\"key\":\"XXXX-XXXX-XXXX-XXXX-XXXX\"}", "create": "2024-12-13 13:05:06" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/getSuscriptorRepeat": { "post": { "operationId": "getSuscriptorRepeat", "summary": "List the subscribers of a plan", "tags": [ "Recurring - Subscribers" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/suscriptores/get-suscriptor-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Recurring plan id." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "2" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "suscriptor": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "modality": { "type": "string" }, "amount": { "type": "string" }, "expire": { "type": "string" }, "coupon": { "type": "string" }, "status": { "type": "string" }, "create": { "type": "string" } } } } } }, "example": { "type": "200", "message": "Success", "suscriptor": [ { "id": 360, "name": "Jhon 1", "lastname": "D", "email": "customer1@example.com", "modality": "Pago mensual prueba repeat modalidad", "amount": "10.00", "expire": "2023-03-26", "coupon": "", "status": "Delete", "create": "2022-10-19 12:48:59" }, { "id": 33364, "name": "Jhon 2", "lastname": "D", "email": "customer2@example.com", "modality": "Pago mensual prueba repeat modalidad", "amount": "10.00", "expire": "2023-08-05", "coupon": "", "status": "Active", "create": "2023-06-05 14:24:18" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/pauseSuscriptorRepeat": { "post": { "operationId": "pauseSuscriptorRepeat", "summary": "Pause a subscriber", "tags": [ "Recurring - Subscribers" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/suscriptores/pause-suscriptor-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id_suscriptor": { "type": "string", "description": "Subscriber id." } }, "required": [ "id_suscriptor", "key" ] }, "example": { "key": "", "id_suscriptor": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/reactiveSuscriptorRepeat": { "post": { "operationId": "reactiveSuscriptorRepeat", "summary": "Reactivate a subscriber", "tags": [ "Recurring - Subscribers" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/suscriptores/reactive-suscriptor-plan" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id_suscriptor": { "type": "string", "description": "Subscriber id." } }, "required": [ "id_suscriptor", "key" ] }, "example": { "key": "", "id_suscriptor": "1" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/recurrentUrl": { "post": { "operationId": "recurrentUrl", "summary": "Get the registration or renewal URL of a plan", "tags": [ "Recurring - Subscribers" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/recurrentes/suscriptores/consult-url" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the Tilopay integration." }, "id": { "type": "string", "description": "Recurring plan id." }, "email": { "type": "string", "description": "Email of the user the registration link is created for." } }, "required": [ "id", "key" ] }, "example": { "key": "", "id": "1", "email": "email@user.com" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "url_register": { "type": "string" }, "url_renew": { "type": "string" } } }, "example": { "type": "200", "message": "", "url_register": "https://app.tilopay.com/admin/recurrent/register/MjMy?email=email@user.com", "url_renew": "" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/processTokenize": { "post": { "operationId": "processTokenize", "summary": "Tokenize a card", "tags": [ "Tokenization" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/tokenizacion/process-tokenize" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect": { "type": "string", "description": "Site where the transaction response is expected." }, "key": { "type": "string", "description": "Key associated with the merchant." }, "email": { "type": "string", "description": "Cardholder email address." }, "language": { "type": "string", "description": "Language [es, en]." }, "firstName": { "type": "string", "description": "Cardholder first name." }, "lastName": { "type": "string", "description": "Cardholder last name." }, "token_version": { "type": "string", "description": "Send the literal value \"v2\"." } } }, "example": { "redirect": "https://urlToRedirect.com", "key": "", "email": "email@user.com", "language": "es", "firstName": "name", "lastName": "lastname", "token_version": "v2" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } }, "example": { "type": "100", "url": "https://secure.tilopay.com/htmls/TOK-5063-740506121440_1648145457file.html" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/user/card-remove": { "post": { "operationId": "cardremove", "summary": "Delete a stored card token", "tags": [ "Tokenization" ], "externalDocs": { "description": "Reference page", "url": "https://www.tilopay.com/developers/api/tokenizacion/remove-card" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key associated with the merchant." }, "email": { "type": "string", "description": "Email of the customer associated with the token." }, "token": { "type": "string", "description": "Token to delete." } }, "required": [ "email", "key" ] }, "example": { "key": "1234-1234-1234-1234-1234", "email": "email@card.com", "token": "411111.......1111" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "type": "200", "status": 1, "message": "Success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token returned by `POST /api/v1/login`, sent as `Authorization: Bearer `." } }, "responses": { "Unauthorized": { "description": "Missing or expired API token.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }