How to integrate Culqi payments into your own system

Culqi is by far the most comfortable Peruvian gateway to integrate: a modern API, documentation in Spanish and a first test charge in under an hour. That is its real merit — and also the origin of almost every problem it causes in production, because how easy it is to start hides the decisions you still have to make. This guide covers what the tutorial leaves out: what changed in 2026, why Yape and PagoEfectivo force you to rethink the architecture, and what separates an integration that works from one that balances.

Culqi or Niubiz?

Culqi wins when you need to ship fast and your volume does not yet justify negotiating a rate: the integration is shorter and so is onboarding. Niubiz wins when volume allows negotiation, when approval rates on Peruvian cards matter, or when anti-fraud carries weight.

It is a decision about stage, not taste. We wrote separately about what it takes to integrate Niubiz — three chained tokens and a longer process. If your case does not call for that yet, Culqi saves you weeks. One detail worth keeping in mind: Culqi belongs to the Credicorp group, BCP’s, which is why it is the most natural path to Yape and Cuotéalo.

First thing to know in 2026: the checkout changed

CulqiJS v2, v3 and v4 are out of support and merchant integration goes through the new Custom Checkout. If you are following a tutorial from a couple of years ago —and there are many— you are building on a foundation that no longer receives maintenance.

It is the most expensive mistake you can make with Culqi today, and it shows up in none of the gateway comparisons: integrating badly is cheap, doing it twice is not. Before writing a line, check any guide —this one included— against the current official documentation. Gateways change versions faster than an article ages.

The card flow: two keys and a token

The public key identifies your merchant and can safely travel to the browser. The secret key lives only on your server and can perform any operation without restriction. The browser tokenizes the card; your backend exchanges that token for the charge.

The important consequence is the same as with any serious gateway: the card never touches your servers. What you receive is a token representing that card within the payment flow. That is what keeps your PCI DSS scope in the manageable range — and the reason building your own card form is not worth it.

A rule that looks obvious and gets broken often: the secret key never in the frontend, never in the repository, never in a client-side environment variable. If it reached the browser, it is no longer secret.

Yape and PagoEfectivo change the architecture, not just the button

With a card, the charge resolves while the customer waits. With wallets and PagoEfectivo it does not: the customer may pay hours later, at an agent or from their app. That is why Culqi’s own documentation states that, given the asynchronous nature of orders, using webhooks is mandatory to receive confirmation.

Here is the most common design mistake: building the whole flow on the browser response because it works with cards, then discovering when you enable PagoEfectivo that there is no browser left to respond to — the customer closed the tab six hours ago and paid at a corner shop. If your system does not listen for the order status change event, that payment exists for Culqi and not for you.

Webhooks done right: respond first, process later

A webhook must return 200 OK immediately and do the heavy work afterwards, outside the request cycle. And it must be idempotent: store the identifiers already processed and discard repeats, because notifications get retried.

This is the part that separates an integration that works from one that balances. If you send the confirmation email, generate the invoice and update inventory before responding, a traffic spike turns your webhooks into timeouts — and timeouts get retried, and retries duplicate. The correct sequence is inverted: acknowledge, enqueue, process.

And as with any gateway, reconciliation is what closes it: regularly cross-checking what Culqi says against what your database says. In the cashier system of a national university that we built, that cross-check is what allows closing the day without reviewing transaction by transaction.

3D Secure: fewer chargebacks, one more step

Culqi applies 3D Secure automatically on cards that require it. It adds a verification step for the customer and, in exchange, shifts fraud liability and reduces chargebacks.

It is not optional when the issuer demands it, so your interface flow has to account for that intermediate verification from the design stage — not as a patch at the end. It is one of those things that shows up in production before sandbox, which is why a real minimum-amount charge with a card that triggers it is worth doing before opening to the public.

Common mistakes when integrating Culqi

Almost all of them come from the same place: the integration was so fast that nobody stopped to decide what happens when the payment does not arrive through the happy path.

How we do it

We integrate Culqi and Niubiz into production systems, with idempotent webhooks, reconciliation and invoicing solved — not just the payment button. We help you pick the right gateway for your stage.

We know the whole path: the gateway integration, the cross-check with your accounting and the SUNAT electronic invoice. If your system needs to charge seriously, let’s talk.

In summary

Culqi is the fastest way to start charging in Peru and the natural door to Yape, PagoEfectivo and Cuotéalo through its ties to Credicorp. Two things decide whether the integration ages well: starting from the current version —CulqiJS v2, v3 and v4 no longer receive support— and treating webhooks as part of the design rather than an extra, because the moment you accept an asynchronous method the browser stops being a source of truth. With that solved, Culqi’s ease stops being a trap and becomes what it promises.