// payments · integrations · peru
How to integrate Niubiz payments into your own system
Niubiz —formerly VisaNet— is the largest card processor in Peru, and that makes it the default gateway for almost any mid-size or large company. It is also, by a wide margin, the most laborious to integrate: where Culqi asks for a key and a form, Niubiz asks for three chained tokens and a backend that knows what to do when something breaks halfway. This is the guide to the parts that actually take work — written from having put it in production, not from reading the manual.
3 tokens
chained to charge once
2 APIs
session and authorization, on your backend
Anti-fraud
the strongest layer in the local market
Negotiable
the rate drops with volume
When Niubiz is the right call — and when it isn’t
Niubiz makes sense when your volume justifies negotiating the rate, when you need the best approval rates on Peruvian cards, or when anti-fraud genuinely matters. If you are validating a product and need to charge next week, Culqi will cost you less work — and saying so is part of giving good advice.
The decision is not technical, it is about stage. Niubiz processes most card transactions in the country and its rate is negotiable at volume: above a certain level of billing, the gap against a flat-rate gateway stops being trivial. In exchange, the integration takes longer and so does the commercial onboarding. If your operation is not there yet, the math rarely works out in favor.
The real flow: three tokens, not one
Charging with Niubiz chains three pieces: security token (authenticates your merchant), session token (authorizes that specific payment session) and transaction token (returned by the form once the customer enters their card). Your backend exchanges the third one for the final authorization.
| Token | Where it lives | What it is for |
|---|---|---|
| Security token | Backend | Authenticates your merchant with username and password. It expires: request it when needed, don’t store it forever. |
| Session token | Backend → Frontend | Authorizes one specific payment session (amount, channel, merchant) and travels to the browser. It has an expiration time. |
| Transaction token | Frontend → Backend | Returned by the Niubiz form once the customer enters their card. It is the piece your backend exchanges for the authorization. |
In practice that is two server-side APIs —one for the session and one for the authorization— plus the checkout script Niubiz serves to render the form in the browser. Endpoints and their versions change, so the developer portal is the only source worth treating as authoritative; what does not change is the shape of the dance.
The important part of that shape: the card never passes through your server. The form belongs to Niubiz and what comes back to your backend is a token, not a PAN. That is what keeps your PCI DSS scope in the manageable range, and the reason not to hand-build the form for the sake of “control” — that control costs a certification.
Trap #1: the customer already paid and your system missed it
Between the form returning the transaction token and your backend receiving the authorization response, there is a window where everything can fail: a timeout, a deploy, a user closing the tab. The charge can exist at Niubiz and not in your database. That window cannot be removed — it has to be designed for.
This is the serious problem with any gateway, and the one that costs the most money when nobody planned for it. The defense has three pieces and none of them is optional:
Record the intent before charging. Your order must exist in your database, in a pending state, before the customer sees the form. If the charge shows up later and finds no order, you have nothing to reconcile it against.
Make the authorization idempotent. If the same transaction token arrives twice —a retry, a double click, a duplicate callback— the second attempt must return the result of the first one, not charge again.
Reconcile against the source of truth. A process that periodically cross-checks what Niubiz says against what your database says and surfaces the differences. In the cashier system of a national university that we built, that cross-check is what allows closing the day without anyone reviewing transaction by transaction.
Trap #2: the purchase number is genuinely unique
The purchaseNumber identifies the purchase at Niubiz and cannot be reused. If your system derives it from something that repeats —the order number after a retry, for instance— you will run into rejections that look random and are not.
It is one of the most time-consuming mistakes because the symptom misleads: the integration “works” in testing and starts failing under real traffic, exactly when retries appear. The practical rule: a new identifier for every charge attempt, stored in your database alongside the order it belongs to, so one order can have several attempts and each attempt its own trail.
Trap #3: refunding is not symmetric to charging
Teams assume that if they charged via API, they refund via API. With Niubiz the refund flow has its own path —including handling from the merchant portal— and it is worth confirming with your account manager before promising a “void” button in your admin panel.
This is not a minor detail: if your product promises self-service refunds and the real flow goes through something else, you have just created manual work for the operations team. Add to that the fact that disputes and chargebacks have their own process — Niubiz publishes a dedicated service to manage them. Settling this during scoping, rather than during launch week, is the difference between a calm release and one that isn’t.
Sandbox: use it, but don’t fully trust it
Niubiz offers a test environment with credentials and test cards. It is enough to validate the full flow, but anti-fraud behavior and real timings only show up in production — so budget for a testing stage with minimum amounts.
The pattern that works for us: close the entire flow in sandbox, go to production with a real minimum-amount charge, verify that reconciliation balances end to end —including the SUNAT electronic invoice where it applies— and only then open charging to the public. It is one extra day of work that saves a week of manual reconciliation.
Common mistakes when integrating Niubiz
Almost every serious problem is not about code: it is about never having decided what happens when the payment succeeds and the system does not hear back.
do it like this
- Create the order in a pending state before showing the form.
- Make the authorization idempotent: the same token twice must not charge twice.
- A new purchaseNumber per attempt, tied to the order in your database.
- Store the full authorization response: you will need it to reconcile and to dispute.
- Confirm the refund and chargeback flow before committing scope.
avoid this
- Building your own card form “for control”: it drags you into the expensive PCI DSS scope.
- Trusting only the browser redirect to mark an order as paid.
- Reusing the purchase number across retries.
- Leaving sandbox as the only test and opening to the public with no real control charge.
- Storing the security token as if it never expired.
How we do it
We integrate Niubiz and Culqi into production systems, with reconciliation and invoicing solved — not just the payment button. We help you pick the right gateway for your stage and build the integration that holds up under real traffic.
We know the whole path: the gateway integration, the cross-check with your accounting and the close that has to balance. If your system needs to charge seriously —and have every charge end up invoiced and reconciled— let’s talk.
In summary
Niubiz is the gateway for companies with volume in Peru, and its price is a more laborious integration: three chained tokens, two APIs on your backend and a form that —thankfully— keeps the card away from your servers. What decides whether the project goes well is not the charging code, but having designed the window between the customer paying and your system finding out: intent recorded first, idempotent authorization, a unique identifier per attempt and a reconciliation that cross-checks against the source of truth. Solve that, and charging stops being scary.
Do you need to charge from your own system?
We have integrated Culqi and Niubiz in production, reconciliation and invoicing included. You talk with the engineer who would build the integration, not a salesperson.