I built a reference template that use NestJS on the backend and Next.js 16 on the frontend, and in this post I want to walk you through the whole thing: what Webpay Plus actually is, why the integration looks the way it does, and how each piece fits together.

Github Repository Reference: Link

A bit of context

Webpay Plus is one of the most important online payment methods in Chile. The user experience is straightforward: your customer enters an amount on your site, gets redirected to Transbank's branded payment page, fills in their card details there, and comes back to your site with a result.

From a UX perspective it's not as slick as Stripe Elements or a fully embedded checkout — the user always sees Transbank's domain in the address bar during the payment — but from a developer's perspective that's actually a feature.

You never touch card numbers. PCI scope stays minimal. Transbank handles 3D Secure, fraud rules, and bank routing.

The trade-off is that the integration model is what you might politely call classical. It's built around full-page redirects and form POSTs, not modern APIs with JSON responses and webhooks. That's important to understand up front, because it shapes every decision you'll make in the code.

The integration flow, step by step

Before looking at any code, it helps to have a clear mental model of what's happening. There are three distinct moments where your system talks to Transbank's system, and each one has a specific shape.

1. First Step: When the customer clicks "Pay", the backend asks Transbank to create a transaction (amount, order ID, return URL). Transbank returns a transaction token and a redirect URL where you must send the user.

2. Second Step: Transbank requires the redirect to be an HTTP POST with the token in a token_ws form field, so you must generate an HTML form with a hidden token_ws input and submit it programmatically to avoid token leakage via history/referrers. Once on Transbank's page, the user enters their card details and either completes or cancels the payment. This step is entirely out of your hands — which, again, is the point.

3. Third Step: When Transbank redirects back with the token_ws, your backend calls Transbank to validate the token and retrieve the transaction details (response_code 0 = approved); then you route the user to a success or error page.

Note: Transbank can POST the return (e.g., on timeout, cancel, or abandonment) to the same return URL instead of a GET, so make sure your backend accepts and handles both POST and GET to avoid broken pages.

Sequence diagram of the steps

Backend Code

The controller stays thin — it reads the incoming parameters, decides which case it's in, and delegates the actual SDK call to the service. Here's the commit handler, which is where most of the interesting logic lives:

Controller example

private tx = WebpayPlus.Transaction.buildForIntegration(
    IntegrationCommerceCodes.WEBPAY_PLUS,
    IntegrationApiKeys.WEBPAY,
);

@All('/commit')
  async callback(@Req() req: Request, @Res() res: Response) {
    const params = req.method === 'GET' ? req.query : req.body;
    const tokenWs = params['token_ws'] as string;
    const tbkToken = params['TBK_TOKEN'] as string;
    const tbkOrdenCompra = params['TBK_ORDEN_COMPRA'] as string;
    const tbkIdSession = params['TBK_ID_SESSION'] as string;

    // Timeout
    if (!tokenWs && !tbkToken) {
      this.logger.warn(
        `[\({req.method}] /webpay/commit timeout tbkOrdenCompra=\){tbkOrdenCompra} tbkIdSession=${tbkIdSession}`,
      );
      return res.redirect('http://localhost:4000/result/error');
    }

    // Abort
    if (tbkToken && !tokenWs) {
      this.logger.warn(
        `[\({req.method}] /webpay/commit abort tbkToken=\){tbkToken} tbkOrdenCompra=${tbkOrdenCompra}`,
      );
      return res.redirect('http://localhost:4000/result/error');
    }

    // Commit TX
    this.logger.debug(`[\({req.method}] /webpay/commit token=\){tokenWs}`);
    const response = await this.webpayService.commitTx(tokenWs);

    if (response.response_code === 0) {
      this.logger.debug(`Commit successful, redirecting to success`);
      return res.redirect('http://localhost:4000/result/success');
    }

    this.logger.warn(`Commit failed responseCode=${response.response_code}, redirecting to error`);
    return res.redirect('http://localhost:4000/result/error');
  }

As you see, the Transbank SDK does most of the heavy lifting. As a example, here's what the "create transaction" call looks like in the webpay.service.ts

async createTx(createWebpayDto: CreateWebpayDto) {

    //TODO: Change buyOrderId with your implementation
    const buyOrder = 'GT-' + Math.floor(Math.random() * 10000) + 1;

    //TODO: Change sessionId with your implementation
    const sessionId = 'Session-' + Math.floor(Math.random() * 10000) + 1;
    const returnUrl = 'http://localhost:3000/webpay/commit';

    this.logger.debug(
      `Creating transaction buyOrder=\({buyOrder} sessionId=\){sessionId} amount=${createWebpayDto.amount}`,
    );

    const response = await this.tx.create(buyOrder, sessionId, createWebpayDto.amount, returnUrl);

    this.logger.debug(`Transaction created token=\({response.token} url=\){response.url}`);

    return response;
  }

Note: The IntegrationCommerceCodes and IntegrationApiKeys constants are public test credentials that Transbank uses as sandbox.

When you go to production, you replace these with your real credentials (which Transbank gives you after a commercial onboarding process) and switch Environment.Integration to Environment.Production.

The returnUrl is the URL Transbank will send the user back to after the payment.

This is critical: it has to be reachable from the user's browser (so no internal hostnames)

And the path you specify is where the callback handler will live on your backend.

Frontend Code

The trickiest part of the integration is step 2: Transbank requires a full-page HTTP POST with the token in a form field — a regular fetch or router.push won't work.

// PaymentForm.tsx
export function PaymentForm() {
  const [amount, setAmount] = useState("");
  const [tx, setTx] = useState<{ token: string; url: string } | null>(null);
  const [isPending, startTransition] = useTransition();
  const formRef = useRef<HTMLFormElement>(null);

  useEffect(() => {
    if (tx) formRef.current?.submit();
  }, [tx]);

  function handlePay() {
    startTransition(async () => {
      const result = await createTransaction(Number.parseInt(amount, 10));
      if ("error" in result) { setError(result.error); return; }
      setTx(result);
    });
  }

  return (
    <>
      {tx && (
        <form ref={formRef} method="post" action={tx.url} className="hidden">
          <input type="hidden" name="token_ws" value={tx.token} />
        </form>
      )}
      {/* amount input + pay button */}
    </>
  );
}

The hidden form only enters the DOM once the token is ready. The useEffect watches for that and calls submit() immediately — the browser performs a full-page POST to Transbank's URL, and the user lands on their payment page.

Then we need a server action that keeps the backend URL off the client entirely:

'use server';
export async function createTransaction(amount: number) {
  const response = await fetch(`${process.env.API_URL}/webpay`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount }),
  });
  return response.json() as Promise<{ token: string; url: string }>;
}

The browser never sees API_URL. The action runs on the Next.js server, proxies the request to NestJS internally, and only { token, url } reaches the client. You can change your backend URL without touching the client bundle.

Handling the result

When Transbank redirects the user back, the backend commits the transaction and redirects to one of two pages in Next.js: /result/success or /result/error. Both are simple static pages — success shows a confirmation, error covers rejections, cancellations, and timeouts alike.

Testing the whole thing

You get a fully functional sandbox without having to sign anything or talk to anyone. They publish test card numbers you can use to simulate approved transactions, declined transactions, and various edge cases.

You can run the full flow end to end on your laptop, with no real money moving anywhere.

To try the template:

git clone https://github.com/figonzal/webpay-nestjs-nextjs 
cd webpay-nestjs-nextjs

• First, run the backend:

cd webpay-nestjs && pnpm install && pnpm start:dev

• The, run the frontend:

cd webpay-nextjs && pnpm install && pnpm dev

Open http://localhost:4000, type any amount, and walk through the full payment flow with one of the test cards. You'll see the redirect to Transbank, the payment form on their side, and the return to your success or error page.

Closing thoughts

The Webpay Plus integration looks intimidating at first because the flow involves multiple redirects, two different HTTP verbs on the same endpoint, and a hidden form trick that feels out of place in 2026. But once you see the three handshakes clearly — create, redirect, commit — the rest is mechanical.

A few things worth keeping in mind as you ship this: the commit endpoint needs to handle three distinct cases, not two. Transbank can return a token_ws (normal flow), a TBK_TOKEN without token_ws (user cancelled), or neither (timeout). The Server Action boundary is also worth preserving — proxying through Next.js keeps your NestJS URL off the client entirely, which pays off when you move from integration to production credentials.

The SDK does most of the work. Your job is to wire the pieces together correctly and handle the unhappy paths.

If this was useful, the full template is on GitHub — Next.js frontend, NestJS backend, Transbank SDK wired up in integration mode, and the full commit handler with all three cases covered. Clone it, run it with the test cards from Transbank's docs, and walk through the complete flow on your laptop before writing a single line of your own integration code. It's a much better starting point than a blank project.

If you liked the article, feel free to give a thumbs up. You will motivate me to write more articles like this one. Thanks! ❤

¡Happy Coding!

In version 1.4.0 of the androidx.activity:activity dependency, Google introduced the new MenuHost interfaces for activities to make it easier to create menus from any component.

But it was not until June 29, 2022, when Google released version 1.5.0 of the androidx.fragment:fragment dependency, where it has officially deprecated the old onCreateOptionsMenu & onOptionsItemSelected override menu functions.

Comparing code

Before

Until before version 1.5.0, inflating a menu was done in the following way:

On the other hand, the management of click events was done in this way:

This way had problems since the use of these fragment APIs generated a close dependency between the fragments and the containing activity, so they are not easy to test.

Now

Android provides a MenuHost and a MenuProvider , so menu creation and click handling are much simpler and no longer rely on the fragments menu APIs.

We only need to call the function addMenuProvider, which forces us to implement the functions to create a menu and the click event handler.

If you noticed, optionally, we can tell the menuhost that the menu is subject to the fragment's life cycle. With this parameter, you can tell the menu at what point in the fragment's life cycle it should be visible (in this case, the resume state).

This comes in handy if you have customized menus for each fragment. At the moment of changing the fragment, the menu will do it with it, respecting its life cycle automatically.

That's all for today ❤

If you liked the article, feel free to give a thumbs up. You will motivate me to write more articles like this one. Thanks!

References

[Android Artifacts]: https://androidx.tech/artifacts/fragment/fragment-ktx/1.5.0

[ChangeLog —Activity]: https://developer.android.com/jetpack/androidx/releases/activity#version_140_3

[ChangeLog — Fragments]: https://developer.android.com/jetpack/androidx/releases/fragment#version_15_2

Therefore, Gradle has decided to support Kotlin for these configuration files using the Kotlin DSL variant.

Here are the changes you need to migrate from Groovy to Kotlin easily:

Build Gradle file (:app)

Adapt dependencies in build.gradle

• Replace all single quotation marks (' ') by double quotation marks (" ")

• You must indicate parentheses where there are function calls.

Adapt plugins inside the files

• The plugins will now go inside a plugins function together with the id function

Build types configuration

• Now the buildTypes must be defined with the function getByName

• Verify that the property values are now assigned with an =

Defaults Configs

• Package configurations, SDK and version names have minor changes

Build Gradle file (MyApp)

Adapt classpath dependencies

• Again note double quotation marks and the use of parentheses.

Changes in Task Clean function

Adapt Settings.gradle

The settings.gradle file should be written in the following way

Finally, change the extension in all files

You must add to each file the extension .kts , the files would look like this:

• app/build.gradle.kts

• build.gradle.kts

• settings.gradle.kts

It's as simple as that!

BONUS ZONE

Load information from keystore

To generate the release signature using the Keystore file you can load the variables in the following way

Load variables from local.properties and exclude library within a dependency

If you have any properties that you need to load from the local file or you need to exclude some library inside of a dependency, you can do it in the following way

That's all for today, I hope your migration to Kotlin will be made easier with this article ❤.

If you liked the article, feel free to give a thumbs up. You will motivate me to write more articles like this one. Thanks!