Checkout API: Initiate a Payment Transaction

The checkout endpoint is the single entry point for initiating a payment transaction in iLeben. It accepts a unified request body and internally routes the operation to the correct payment gateway driver — Transbank (Webpay Plus), Mercado Pago, or manual bank transfer. The response shape differs per gateway, so clients should inspect the gateway field to determine how to handle the result.

Authentication

All checkout and gateway-listing endpoints require both auth:sanctum and token.origin middleware:

Header: Authorization: Bearer <token>
Header: Origin: <your-authorized-origin> (or Referer / X-Authorized-Url)

GET /api/v1/payment-gateways

List the payment gateways available for a given plant before presenting the checkout form. Pass the target plant ID as a query parameter to filter gateways by project-level configuration.

GET /api/v1/payment-gateways?plant_id={id}

Query parameters

plant_id

integer

The ID of the plant unit the user intends to purchase. When provided, gateways that are not configured for the plant’s project are excluded from the response.

Response

gateways

array

Array of available gateway objects.

Show gateway object fields

string

Gateway identifier used in the checkout request, e.g. "transbank", "mercadopago", "manual".

name

string

Human-readable gateway name, e.g. "Webpay (Transbank)".

flow

string

Payment flow type: "redirect" for Transbank and Mercado Pago, or "manual" for bank transfer.

description

string

Short description shown to the buyer, e.g. "Paga con tarjeta de credito o debito".

count

integer

Total number of available gateways returned.

Example response

{
  "gateways": [
    {
      "id": "transbank",
      "name": "Webpay (Transbank)",
      "flow": "redirect",
      "description": "Paga con tarjeta de credito o debito"
    }
  ],
  "count": 1
}

POST /api/v1/checkout

Initiate a checkout transaction for a plant. The gateway field determines which payment driver is invoked and which response fields are returned.

Request body

plant_id

integer

required

ID of the plant unit being purchased.

quantity

integer

required

Number of units. Typically 1 for real estate plant purchases.

gateway

string

required

Payment gateway to use. Accepted values: "transbank", "mercadopago", or "manual".

name

string

required

Full name of the buyer for billing and identification purposes.

string

required

Buyer’s email address. Used for payment notifications and receipts.

phone

string

required

Buyer’s phone number, e.g. "+56911111111".

rut

string

required

Buyer’s Chilean RUT identifier, e.g. "12345678-5".

session_token

string

Required when gateway is "manual". The session_token returned from a prior POST /api/v1/reservations call. An active reservation must exist for the specified plant_id.

Request body example

{
  "plant_id": 10,
  "quantity": 1,
  "gateway": "transbank",
  "name": "Juan Perez",
  "email": "juan@example.com",
  "phone": "+56911111111",
  "rut": "12345678-5",
  "session_token": "opcional-no-manual"
}

Response shapes

Response fields differ depending on which gateway was selected.

Transbank
Mercado Pago
Manual

Transbank returns a redirect URL and a transaction token. Redirect the user to redirect_url to complete payment on the Webpay Plus hosted page.

gateway

string

Always "transbank" for this driver.

redirect_url

string

Full URL to redirect the user to for card payment on Transbank’s hosted page.

token

string

Transbank transaction token (token_ws). Appended to redirect_url as a query parameter by the SDK.

payment_id

integer

Internal iLeben payment record ID.

payment_status_token

string

Token used to poll the public status endpoint (GET /api/v1/payments/public-status/{id}?token=...) without authentication.

amount

number

Transaction amount in the configured currency (CLP by default).

description

string

Line-item description of the purchase, e.g. "1x Depto 301".

environment

string

Transbank environment in use: "integration" or "production".

Mercado Pago returns a redirect URL pointing to the MP-hosted checkout. Redirect the user there to complete payment. MP will deliver the result via asynchronous webhook to POST /payments/mercadopago/webhook.

gateway

string

Always "mercadopago" for this driver.

redirect_url

string

The Mercado Pago init_point URL. Redirect the user here to complete payment on MP’s hosted checkout.

preference_id

string

Mercado Pago preference ID for this transaction, used to track the payment on the MP side.

amount

number

Transaction amount in the configured currency.

description

string

Line-item description of the purchase, e.g. "1x Depto 301".

Manual payments are used for bank transfers or cash. The response provides transfer instructions and banking details. After the buyer sends the transfer, they upload proof via POST /api/v1/payments/{id}/manual-proof.

flow

string

Always "manual" for this driver.

gateway

string

Always "manual" for this driver.

payment_id

integer

Internal iLeben payment record ID.

reference

string

Unique payment reference the buyer should include in the transfer.

amount

number

Transaction amount in the configured currency.

currency

string

Currency code, e.g. "CLP".

description

string

Line-item description of the purchase, e.g. "1x Depto 301".

status

string

Initial payment status, typically "pending_approval" for manual payments.

instructions

string

Human-readable transfer instructions shown to the buyer.

bank_accounts

array

Array of bank account objects with the destination banking details.

payment_link

string

Optional URL to an external payment portal configured by the project, or null if not set.

requires_proof

boolean

Whether the buyer is required to upload a transfer proof via POST /api/v1/payments/{id}/manual-proof.

expires_at

string

ISO 8601 datetime by which the manual payment must be completed.

cURL examples

Transbank checkout

curl -X POST "https://tu-dominio.com/api/v1/checkout" \
  -H "Authorization: Bearer TOKEN" \
  -H "Origin: https://frontend.cliente.com" \
  -H "Content-Type: application/json" \
  -d '{
    "plant_id": 10,
    "quantity": 1,
    "gateway": "transbank",
    "name": "Juan Perez",
    "email": "juan@example.com",
    "phone": "+56911111111",
    "rut": "12345678-5"
  }'

Reservation + manual checkout (two-step flow)

First, create a reservation to hold the plant and obtain a session_token:

curl -X POST "https://tu-dominio.com/api/v1/reservations" \
  -H "Authorization: Bearer TOKEN" \
  -H "Origin: https://frontend.cliente.com" \
  -H "Content-Type: application/json" \
  -d '{"plant_id": 10}'

Then initiate checkout using the returned session_token:

curl -X POST "https://tu-dominio.com/api/v1/checkout" \
  -H "Authorization: Bearer TOKEN" \
  -H "Origin: https://frontend.cliente.com" \
  -H "Content-Type: application/json" \
  -d '{
    "plant_id": 10,
    "quantity": 1,
    "gateway": "manual",
    "name": "Juan Perez",
    "email": "juan@example.com",
    "phone": "+56911111111",
    "rut": "12345678-5",
    "session_token": "TOKEN_RESERVA"
  }'

session_token is required for the manual gateway and must come from an active, non-expired reservation for the same plant_id. If the reservation has expired or the token is missing, the request will be rejected. Always create a new reservation immediately before initiating a manual checkout.

Payment result webhooks and redirects

After checkout, gateways post results back through web routes defined outside /api/v1:

Gateway	Route	Method
Transbank	`/payments/transbank/return`	`GET` or `POST`
Mercado Pago	`/payments/mercadopago/webhook`	`POST` (async)
Mercado Pago	`/payments/mercadopago/return`	`GET` (user redirect)

Final result pages:

Outcome	Route
Success	`GET /payments/success/{payment?}`
Failed	`GET /payments/failed/{payment?}`
Pending	`GET /payments/pending/{payment?}`

Overview

Public Endpoints

Authenticated Endpoints

Checkout API: Initiate a Payment Transaction

Authentication

GET /api/v1/payment-gateways

Query parameters

Response

Example response

POST /api/v1/checkout

Request body

Request body example

Response shapes

cURL examples

Transbank checkout

Reservation + manual checkout (two-step flow)

Payment result webhooks and redirects

Build docs developers (and LLMs) love

Overview

Public Endpoints

Authenticated Endpoints

Documentation Index

​Authentication

​GET /api/v1/payment-gateways

​Query parameters

​Response

​Example response

​POST /api/v1/checkout

​Request body

​Request body example

​Response shapes

​cURL examples

​Transbank checkout

​Reservation + manual checkout (two-step flow)

​Payment result webhooks and redirects

Build docs developers (and LLMs) love

Authentication

GET /api/v1/payment-gateways

Query parameters

Response

Example response

POST /api/v1/checkout

Request body

Request body example

Response shapes

cURL examples

Transbank checkout

Reservation + manual checkout (two-step flow)

Payment result webhooks and redirects