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 Credicorp —the group behind BCP— 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: the card never touches your servers. What you receive is a token representing it within the payment flow, and that boundary is what keeps your PCI DSS questionnaire short. Worth underlining here in particular, because Culqi makes the opposite easy: the API is so comfortable that the temptation appears to “just capture the number myself and send it over”. That is where the short path is lost, and coming back costs far more than never having left.

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 the webhook is not the end of the road either. A webhook that never arrived does not announce that it never arrived: the only signal is the balance. That is why regularly cross-checking what Culqi says against what your database says is not a month-end chore — it is part of the integration, and it belongs on the schedule from day one, not from the day money goes missing.

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

Culqi integrates in an afternoon, and that is exactly the problem: nobody stops to decide what happens when the payment does not arrive through the happy path.

How we do it

With Culqi the risk is not integrating: it is integrating fast and finding out in month three that the books do not balance. We put the webhooks, the idempotency and the reconciliation in from the start, so today’s speed does not bill you later.

We work on gateway integration all the way to the end of the road: from the token to the accounting entry, by way of the SUNAT electronic invoice. If you are starting with Culqi, start well — 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.