Implementation Guides

Step-by-step guides for different business models.

Guide: E-commerce

The standard flow for online stores, retail, and platforms where customers pay at checkout.

This flow uses Transbank Webpay Plus, the most common integration. It redirects the customer to Transbank's secure portal to enter their card details and then returns them to your site. Your server must then confirm the transaction to finalize the payment.

Create Transaction Required

Initiate the payment process by sending the transaction details to our API. This will return a unique token and a URL to redirect the customer to.

POST /api/v1/webpay/transactions

Create Webpay Transaction

Create a new Webpay Plus transaction.

Example Request:


curl -X POST "https://jupipay.app/api/v1/webpay/transactions" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data-raw '{
    "amount": 10000,
    "return_url": "https://your-store.com/webpay/callback"
}'

Example Success Response:


{
  "success": true,
  "message": "Transaction created successfully",
  "data": {
    "transaction": {
      "token": "e8ad219e273f8e4a3df5db8ac62c62c8a38a719cbf4b5d4b5d4b5d4b5d4b5d4b",
      "url": "https://webpay3gint.transbank.cl/webpayserver/initTransaction",
      "buy_order": "WEB-1678886400",
      "session_id": "sid_62c62c8a38a719cbf4b",
      "amount": 10000,
      "return_url": "https://your-store.com/webpay/callback"
    },
    "correlation_id": "corr_id_12345"
  }
}

Redirect Customer

Use the `url` from the previous response to redirect the customer to Transbank's secure payment page.

Example (PHP):


// Assuming the API call response is in $apiResponseData (as an associative array)
$redirectUrl = $apiResponseData['data']['transaction']['url'];

// Redirect the user to Transbank to complete the payment
header('Location: ' . $redirectUrl);
exit;

Confirm Transaction Required

After payment, Transbank redirects the user back to your `return_url`. You'll receive a `token_ws` (or `TBK_TOKEN` if aborted). You MUST use this token to confirm the transaction status with our API.

PUT /api/v1/webpay/transactions/{token}/commit

Confirm Webpay Transaction

Confirm a Webpay Plus transaction.

Example (Laravel Route and Controller):


// in routes/web.php
Route::any('/webpay/callback', 'WebpayController@callback');

// in WebpayController.php
public function callback(Request $request)
{
    $token = $request->input('token_ws') ?? $request->input('TBK_TOKEN');

    if (!$token) {
        // Handle failed transaction (timeout, etc.)
        return view('payment.error_timeout');
    }

    // Call your backend to hit the confirmation endpoint
    $response = Http::withToken('YOUR_API_KEY')->put(
        "https://jupipay.app/api/v1/webpay/transactions/{$token}/commit"
    );

    $commitData = $response->json('data');

    if ($response->successful() && $commitData['transaction']['is_approved']) {
        // Payment was successful!
        // Update your order status, show a success page.
        return view('payment.success', ['transaction' => $commitData['transaction']]);
    } else {
        // Payment was rejected or an error occurred.
        return view('payment.failed', [
            'transaction' => $commitData['transaction'] ?? null,
            'error' => $response->json('message', 'Unknown error')
        ]);
    }
}

Guide: SaaS & Subscriptions

For businesses that require recurring billing, such as monthly or annual software subscriptions.

This flow uses Transbank Patpass, which allows a customer to authorize future automatic payments. You first inscribe the customer, and then our system can automatically charge their registered payment method on a recurring basis.

Start Subscription Inscription Required Once

Initiate the subscription by providing the customer's details. The API returns a URL for the user to authorize the recurring payment mandate.

POST /api/v1/patpass/subscriptions

Create Patpass Subscription

Start a new Patpass subscription inscription.

Example Request:


curl -X POST "https://jupipay.app/api/v1/patpass/subscriptions" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data-raw '{
    "rut": "11111111-1",
    "name": "John",
    "last_name": "Doe",
    "patpass_name": "My SaaS Monthly Plan",
    "person_email": "john.doe@example.com",
    "commerce_email": "notifications@your-saas.com",
    "max_amount": 50000,
    "return_url": "https://your-saas.com/patpass/callback",
    "final_url": "https://your-saas.com/patpass/thank-you"
}'

Example Success Response:


{
  "success": true,
  "message": "Subscription created successfully",
  "data": {
    "subscription": {
      "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
      "url": "https://webpay3gint.transbank.cl/webpayserver/inscription",
      "service_id": "sid_123456789"
    },
    "correlation_id": "corr_id_patpass_123"
  }
}

Redirect & Confirm Subscription

Redirect the user to the `url` provided. After they authorize, Transbank sends them to your `return_url`. You MUST then call our API with the received `TBK_TOKEN` to confirm and activate the subscription.

PUT /api/v1/patpass/subscriptions/{token}/confirm

Confirm Patpass Subscription

Confirm and activate a Patpass subscription.

Example (Laravel Route and Controller):


// in routes/web.php
Route::any('/patpass/callback', 'PatpassController@callback');

// in PatpassController.php
public function callback(Request $request)
{
    // Token sent back by Transbank after user authorizes the mandate
    $token = $request->input('TBK_TOKEN');

    if (!$token) {
        // Handle failed inscription
        return view('subscription.failed');
    }

    // Call your backend to hit the confirmation endpoint
    $response = Http::withToken('YOUR_API_KEY')->put(
        "https://jupipay.app/api/v1/patpass/subscriptions/{$token}/confirm"
    );

    if ($response->successful()) {
        // Subscription is confirmed and active!
        $subscriptionData = $response->json('data')['subscription'];

        // Store the subscription details, especially the `subscription_id`
        // e.g., associate $subscriptionData['subscription_id'] with the user in your database

        return view('subscription.success', ['subscription' => $subscriptionData]);
    } else {
        return view('subscription.failed', ['error' => $response->json('message')]);
    }
}

Charge the Subscription

Once the subscription is active, you can charge it on a recurring basis (e.g., via a scheduled job) using its unique `subscriptionId`.

POST /api/v1/patpass/subscriptions/{subscriptionId}/charge

Charge Subscription

Execute a charge on an active Patpass subscription.

Example (Backend charge):


// The subscriptionId obtained from the confirmation step
$subscriptionId = '...'; // The subscription_id saved from the confirmation step
$amount = 29990; // e.g., monthly fee
$commerceOrder = 'SAAS-SUB-CHARGE-' . uniqid();

$response = Http::withToken('YOUR_API_KEY')->post(
    "https://jupipay.app/api/v1/patpass/subscriptions/{$subscriptionId}/charge",
    [
        'amount' => $amount,
        'commerce_order' => $commerceOrder,
    ]
);

if ($response->successful()) {
    // Charge was successful
    Log::info("Successfully charged subscription {$subscriptionId}");
} else {
    // Charge failed
    Log::error("Failed to charge subscription {$subscriptionId}: " . $response->body());
}

Guide: Marketplaces

For platforms connecting multiple vendors with customers, requiring payments to be split or managed on behalf of sellers.

This flow uses Transbank Oneclick for deferred payments, allowing you to register a customer's card once and then charge it later for subsequent purchases from different vendors in your marketplace, simplifying the checkout process.

Inscribe User's Card Required Once

First, register the user's payment method (credit/debit card) with Transbank. This creates a secure token (`inscription_id`) that you can use for future charges.

POST /api/v1/oneclick/inscriptions

Start Oneclick Inscription

Start the Oneclick inscription process.

Example Request:


curl -X POST "https://jupipay.app/api/v1/oneclick/inscriptions" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data-raw '{
    "username": "user_unique_identifier_123",
    "email": "customer@example.com",
    "response_url": "https://your-marketplace.com/oneclick/finish"
}'

Example Success Response:


{
  "success": true,
  "message": "Inscription started successfully",
  "data": {
    "inscription": {
      "token": "01abf2be78a5b2857e873918a3818e6c7050519342455953534b868e4f5853f7",
      "url_webpay": "https://webpay3gint.transbank.cl/webpayserver/inscription",
      "username": "user_unique_identifier_123"
    },
    "correlation_id": "corr_id_oneclick_123"
  }
}

Redirect the user to the `url_webpay` to authorize the inscription in Transbank's portal.

Finish Inscription

After the user completes the process on Transbank's site, they are redirected back to your `return_url`. A `TBK_TOKEN` is sent. Use this token to confirm and finalize the inscription.

PUT /api/v1/oneclick/inscriptions/{token}/confirm

Finish Oneclick Inscription

Finish the Oneclick inscription process.

Example Request (User is redirected here):


// Your endpoint: https://your-marketplace.com/oneclick/finish
// Transbank will POST a 'TBK_TOKEN' to this URL.

// Example Controller Logic
public function finishOneclick(Request $request)
{
    $tbkToken = $request->input('TBK_TOKEN');

    // Make a call to your backend to hit the finish endpoint
    $response = Http::withToken('YOUR_API_KEY')->put(
        "https://jupipay.app/api/v1/oneclick/inscriptions/{$tbkToken}/confirm"
    );

    if ($response->successful()) {
        // The card is now registered!
        $inscriptionData = $response->json('data')['inscription'];

        // Store `tbk_user` for this user for future charges.
        // e.g., $user->update(['tbk_user' => $inscriptionData['tbk_user']]);

        return view('marketplace.inscription-success', ['inscription' => $inscriptionData]);
    } else {
        return view('marketplace.inscription-failed', ['error' => $response->json('message')]);
    }
}

Example Success Response from API:


{
  "success": true,
  "message": "Inscription confirmed successfully",
  "data": {
    "inscription": {
      "tbk_user": "a9b8c7d6-e5f4-g3h2-i1j0-k9l8m7n6o5p4",
      "authorization_code": "1213",
      "card_type": "Visa",
      "card_number": "************6623",
      "response_code": 0,
      "status": "Inscription Approved",
      "is_approved": true
    },
    "correlation_id": "corr_id_oneclick_456"
  }
}

3
Authorize a Charge

With the card inscribed, you can now charge it for any purchase. You can charge the card for the full cart amount and handle payouts to vendors yourself.

POST /api/v1/oneclick/inscriptions/authorize

Authorize Oneclick Charge

Authorize a charge for an inscribed card.

Example Request:
```
curl -X POST "https://jupipay.app/api/v1/oneclick/inscriptions/authorize" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data-raw '{
    "username": "user_unique_identifier_123",
    "tbk_user": "a9b8c7d6-e5f4-g3h2-i1j0-k9l8m7n6o5p4",
    "buy_order": "marketplace-order-98765",
    "amount": 20000
}'
```
Note: A successful response means the transaction was authorized and the funds will be captured. No further confirmation step is needed.

JupiPay

Implementation Guides

Guide: E-commerce

Create Transaction Required

Create Webpay Transaction

Redirect Customer

Confirm Transaction Required

Confirm Webpay Transaction

Guide: SaaS & Subscriptions

Start Subscription Inscription Required Once

Create Patpass Subscription

Redirect & Confirm Subscription

Confirm Patpass Subscription

Charge the Subscription

Charge Subscription

Guide: Marketplaces

Inscribe User's Card Required Once

Start Oneclick Inscription

Finish Inscription

Finish Oneclick Inscription

Authorize a Charge

Authorize Oneclick Charge