Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/scooller/Leben-site/llms.txt

Use this file to discover all available pages before exploring further.

iLeben integrates with Transbank Webpay Plus (single commerce code) and Webpay Mall (multiple commerce codes per project) using the official transbank/transbank-sdk v5.x PHP package. Transbank is the primary payment method for Chilean buyers and processes both debit and credit cards through a hosted payment page. The integration follows a redirect-and-confirm pattern: the SDK generates a one-time token and URL, the user completes payment on Transbank’s page, and the platform confirms the transaction on return.

​
Configuration

Set the following variables in your .env file before enabling the gateway: 
# 'integration' uses SDK test credentials automatically
# 'production' requires TRANSBANK_COMMERCE_CODE and TRANSBANK_API_KEY
TRANSBANK_ENVIRONMENT=integration

# Only required when TRANSBANK_ENVIRONMENT=production
TRANSBANK_COMMERCE_CODE=597055555532
TRANSBANK_API_KEY=579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C

​
Transbank Mall Mode

When a single Salesforce project needs its own commerce code, enable Mall mode and supply a JSON map of project keys to store codes: 
TRANSBANK_MALL_MODE=true
TRANSBANK_STORE_CODES='{"leben":"597035563628"}'
In integration mode, the SDK automatically applies Transbank’s official test credentials. The values of TRANSBANK_COMMERCE_CODE and TRANSBANK_API_KEY in .env are ignored and only take effect when TRANSBANK_ENVIRONMENT=production.

​
Payment Flow

1

Initiate checkout

The frontend calls POST /api/v1/checkout with gateway: "transbank" in the request body. The API creates a Payment record with status pending and calls TransbankService::createTransaction().
2

Receive redirect token

The API responds with a redirect_url and a token_ws. Both are needed to send the user to Transbank’s hosted payment page.
3

Redirect the user

The frontend redirects the user to redirect_url?token_ws={token}. Transbank presents the card-entry form.
4

User completes payment

Transbank processes the card and sends the user back to the configured return URL via an HTTP POST.
5

Return POST received

PaymentWebhookController@transbankReturn handles the GET|POST /payments/transbank/return route. The controller extracts token_ws (or TBK_TOKEN on cancellation) from the incoming request.
6

Confirm with SDK

The service calls confirmTransaction($token) against the Transbank API. The SDK returns response_code, amount, authorization_code, and card_detail.
7

Update payment status

The Payment record is updated based on response_code: 0 maps to completed; any other code maps to failed.
8

Redirect to result page

The user is redirected to /payments/success/{payment} on success or /payments/failed/{payment} on failure.

​
PHP Example

The following snippet shows the full Transbank flow as used internally. Import PaymentGatewayFacade to keep the driver abstraction: 
use App\Models\Payment;
use App\Enums\PaymentGateway;
use App\Enums\PaymentStatus;
use App\Facades\PaymentGateway as PaymentGatewayFacade;

// 1. Persist the payment record
$payment = Payment::create([
    'user_id'    => auth()->id(),
    'project_id' => $project->id,
    'plant_id'   => $plant->id,
    'gateway'    => PaymentGateway::TRANSBANK,
    'amount'     => 10000,
    'currency'   => 'CLP',
    'status'     => PaymentStatus::PENDING,
    'metadata'   => ['buy_order' => 'ORDER-' . time()],
]);

// 2. Start the transaction — SDK returns token + URL
$transaction = PaymentGatewayFacade::driver('transbank')->createTransaction([
    'amount'     => $payment->amount,
    'buy_order'  => $payment->metadata['buy_order'],
    'session_id' => 'session-' . $payment->id,
]);

// 3. Redirect the user to Transbank
return redirect($transaction['url'] . '?token_ws=' . $transaction['token']);

// 4. The return is handled automatically at:
// GET|POST /payments/transbank/return → PaymentWebhookController@transbankReturn

​
SDK Methods

MethodSignatureDescription
createTransactioncreateTransaction(array $data): arrayInitiates a new Webpay transaction; returns token and url
confirmTransactionconfirmTransaction(string $token): arrayConfirms the transaction after the user returns; returns authorization details
getTransactionStatusgetTransactionStatus(string $token): arrayQueries the current state of a transaction by its token
refundTransactionrefundTransaction(string $token, ?float $amount = null): arrayIssues a full or partial refund for a completed transaction

​
Test Cards

Use these cards in integration mode. Any future expiry date and CVV 123 are accepted.
TypeCard NumberExpected Result
Debit (success)4051 8856 0000 0002Approved
Credit (success)4051 8860 0000 0001Approved
Rejected4051 8842 3993 7763Declined

​
Web Routes

MethodRouteHandlerDescription
GET/payments/transbank/redirectPaymentWebhookControllerBridge endpoint for POST redirect to Webpay
GET|POST/payments/transbank/returnPaymentWebhookController@transbankReturnReceives the user return and token from Transbank

​
Error Reference

Error MessageCauseResolution
Invalid commerce codeTRANSBANK_ENVIRONMENT=production but integration credentials are in .env, or vice versaEnsure TRANSBANK_ENVIRONMENT matches the actual credential set. In integration mode the SDK ignores .env credentials entirely.
Transaction not foundThe token_ws has expired — Transbank tokens are only valid for 15 minutesCreate a new transaction by restarting the checkout flow.

​
Log Sanitization

All Transbank service calls are logged to storage/logs/laravel.log. Tokens (token_ws, TBK_TOKEN) and raw SDK payloads are sanitized before writing to prevent PII or secret leakage in log storage. 
# Tail Transbank-related log entries in real time
tail -f storage/logs/laravel.log | grep -i "Transbank"

Build docs developers (and LLMs) love

Get started for freeTalk to us