Kueski

Who should use this guideThis guide is intended for merchants who:

Use Payrails as a payment orchestrator
Use Payrails to offer Kueski Pay buy now, pay later in Mexico
Have an active Kueski Pay merchant account

Create a Kueski integration in Payrails

Log in to the Payrails portal.
Go to Settings → Integrations.
Select Add instance to create a new integration configuration.
Select the workspaces where this integration should be available.

About workspacesWorkspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.

Step 1: Choose the integration type

Select Payment.
Continue to the next step.

Step 2: Choose the provider

Select Kueski.
Continue to the next step.

A screenshot showing Kueski selected as the provider.

Step 3: Configure your Kueski integration

What you’ll need from KueskiBefore you begin, make sure you have your Kueski API key and secret key. Kueski provides them when it sets up your account.

Integration instance name

An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

In Payrails

Enter an Instance name for your integration, for example merchant_kueski.

A screenshot showing the integration instance name field.

Credentials

In Payrails

Field	Value
API Key	Your Kueski API key
API Secret	Your Kueski secret key. Payrails signs refund requests with it and verifies Kueski’s notifications.

Payrails sends requests to the Kueski testing environment in test mode and to the live environment in live mode, so use the keys for the matching environment.

A screenshot showing the Kueski credential fields.

Payment methods

In Payrails

Select Kueski.

A screenshot showing the Kueski payment method selection.

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.

Create webhooks in the same mode (test or live) as your Payrails integration.

In Payrails

Copy the Notification URL shown under Account configuration at the top of the integration form.

In Kueski

Send the Payrails notification URL to Kueski, and ask them to set it as the notification URL for your account.
When Kueski confirms, run a test payment and check that the payment status updates in Payrails.

Request fields for Kueski

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to Kueski when you include them. For more about meta fields, refer to Meta fields.

Field	Status	Description
`amount`	Required	Sent to Kueski as the total amount and currency. Use MXN.
`merchantReference`	Required	Sent as the order ID.
`meta.order.description`	Required	Sent as the payment description.
`meta.order.lines`	Required	At least one line, each with `id`, `name`, `description`, `unitPrice` and `quantity`. Payrails sends lines with `type` set to `lineItem` as the items. The lines, tax, discount and shipping must add up to `amount`.
`meta.order.deliveryAddress`	Required	Sent as the shipping address. Include `street`, `city`, `state`, `postalCode` and `country.code`.
`meta.order.deliveryAddress.lastName`	Required	Sent as the shipping name. You can send `meta.customer.name` and `meta.customer.lastName` instead.
`meta.order.deliveryAddress.doorNumber`, `meta.order.deliveryAddress.area`	Optional	Sent as the interior number and neighborhood.
`meta.customer.email`, `meta.customer.phone.number`	Optional	Sent as the shipping email and phone number.
`meta.order.billingAddress`	Optional	Sent as the billing address. When you send it, include the same address fields as the delivery address.
`returnInfo.cancelUrl`	Optional	Sent as the URL Kueski returns your customer to when they cancel.

Kueski payments are captured straight away, so use instant capture in your workflow.

Enable the integration

In Payrails

Select Save account to enable the integration.
Confirm the integration shows as Enabled.

Your Kueski integration is now ready to process payments.

Next steps

Run a test Kueski Pay payment in the Kueski testing environment.
Verify that:
- Your customer is redirected to Kueski and back to your site.
- The payment status updates correctly in Payrails.
Once verified in test mode, repeat the setup in live mode.

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a Kueski integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider