Culqi
Connect Culqi to PayLexer to accept card payments via an embedded checkout form for Peru-based merchants and customers.
Culqi is a Peruvian payment gateway that lets merchants accept card payments through an embedded checkout form that opens directly on the merchant's own store page. The Culqi checkout form collects the card securely in the shopper's browser, and PayLexer completes the charge on the server. Through PayLexer, Culqi supports one-time card payments and full or partial refunds for merchants serving customers in Peru and internationally.
- Supported Regions (Merchant Accounts): Peru
- Supported Currencies: PEN (Peruvian sol), USD
Supported Features
- Card payments via Culqi's embedded on-page checkout form
- Full and partial refunds - multiple partial refunds are allowed up to the original charge amount
- Real-time payment notifications via webhooks
- Automatic 30-minute safety-net polling to catch any missed webhook notifications
- Test and Live environments via separate key pairs
Before You Start
Make sure you have:
- Culqi Account – Don't have one? Sign up for Culqi →
- PayLexer Account – Required to configure the integration. Create your account →
- A website where you want to integrate
Looking for a different payment processor? View all supported gateways →
Configuring Culqi
You need a Public Key and Secret Key from Culqi for this integration. Culqi provides separate key pairs for Test and Live environments.
Getting API Credentials
Find your API keys in CulqiPanel
Log in to CulqiPanel and navigate to Desarrollo / API Keys in the left sidebar.
Your Public Key is shown at the top of the page. Click Ver to reveal your Secret Key.
Copy both the Public Keyand** Secret Key** for the environment you need - you will need them in the next step.
Adding Credentials to PayLexer
Open PayLexer Dashboard
Log in to your PayLexer dashboard and navigate to Payment Gateways → Culqi.
Enter your credentials
Paste your Live and Test key pairs into the respective fields.
Understanding Live/Production and Sandbox Settings:
| Environment | Purpose |
|---|---|
| Live / Production (Mandatory) | Used for real transactions. Cannot be empty - enter a placeholder if you are not yet ready to go live. |
| Test / Sandbox (Optional) | Used for testing only. No real money is processed. |
How PayLexer selects credentials:
- Debug/Test mode ON → Test credentials are used
- Debug/Test mode OFF → Live credentials are used
Test and save
Click Test Connection to verify your credentials, then click Save Configuration.
Credentials saved. Continue to the Webhooks section below before enabling Culqi on your website.
Configuring Webhooks (Mandatory)
Webhooks enable real-time payment updates and significantly improve reliability.
Benefits of Webhooks:
- Instant payment status updates
- Automatic refund processing
- Dispute notifications
Copy the PayLexer webhook URL
In your PayLexer dashboard under Payment Gateways → Culqi, copy the Webhook URL shown on the configuration page.
Register the webhook in CulqiPanel
Log in to CulqiPanel and navigate to Eventos → Webhooks → +Añadir.
Paste the PayLexer webhook URL and select the following event types:
- Cargos (Charges)
- Devoluciones (Refunds)
- Órdenes (Orders)
Save the webhook.
Culqi webhook notifications do not include a cryptographic signature. PayLexer automatically re-verifies every notification directly with Culqi before updating an order, so only genuine events are ever recorded. If a notification is missed, PayLexer's 30-minute safety-net polling catches and resolves the order automatically.
Integrate Culqi to Your Website
If you have already added and configured your site, you can enable Culqi in your existing setup.
Go to Websites
Navigate to Websites in your PayLexer dashboard.
Edit your website
Click the Edit Icon of your added website.
Enable Culqi
Click the checkbox to enable Culqi for the website.
Culqi is now active for this website. Run a test transaction before switching off Debug/Test mode.
If you haven't added a website yet, Continue to Add Your Website →
Troubleshooting
Best Practices
- Run at least one full test transaction before going live. Use your
pk_test_/sk_test_key pair in PayLexer's Test fields so no real money is processed. - Register the PayLexer webhook URL in CulqiPanel as soon as you configure the integration. Without webhooks, payment confirmations rely entirely on the 30-minute polling cycle.
- Keep your Secret Keys confidential. If a key is compromised, regenerate it from CulqiPanel and update it in PayLexer immediately.
- Culqi only supports PEN and USD. Ensure your checkout currency is set to one of these before enabling Culqi on a website.
- Partial refunds are supported - you can issue multiple partial refunds on a single charge as long as the total does not exceed the original amount.
FAQs
Still Have Questions?
- Culqi Support: Culqi Help Center
- PayLexer Support: Contact Support
For API references and advanced configuration, see the Culqi developer documentation.