> ## Documentation Index > Fetch the complete documentation index at: https://docs.payrails.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. > Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. > Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. > Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. > Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. > Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. > Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. # Kueski > Connect Kueski to Payrails to accept Kueski Pay buy now, pay later payments in Mexico, covering your API keys and notifications. ![Kueski logo](https://assets.payrails.io/img/logos/kueski/logo-full-bleed.svg) > [!NOTE] > > **Who should use this guide** > > This 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 1. Log in to the **Payrails** portal. 2. Go to **Settings** → **Integrations**. 3. Select **Add instance** to create a new integration configuration. 4. Select the **workspaces** where this integration should be available. > [!NOTE] > > **About workspaces** > > Workspaces 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.](https://mintcdn.com/payrails-42074109/G6I_sRu5_wvriVNB/images/docs/kueski-image-01.png?fit=max\&auto=format\&n=G6I_sRu5_wvriVNB\&q=85\&s=ba4bbb7521cab2680ed0e81dce4a95fa) *** ## Step 3: Configure your Kueski integration > [!TIP] > > **What you'll need from Kueski** > > Before 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.](https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max\&auto=format\&n=145W1v58K5wnDMNC\&q=85\&s=470be58979509680650b0cbf8b5eecc4) *** ### 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.](https://mintcdn.com/payrails-42074109/G6I_sRu5_wvriVNB/images/docs/kueski-image-02.png?fit=max\&auto=format\&n=G6I_sRu5_wvriVNB\&q=85\&s=c061d468417910e971061d78b24cdfcd) *** ### Payment methods **In Payrails** * Select **Kueski**. ![A screenshot showing the Kueski payment method selection.](https://mintcdn.com/payrails-42074109/G6I_sRu5_wvriVNB/images/docs/kueski-image-03.png?fit=max\&auto=format\&n=G6I_sRu5_wvriVNB\&q=85\&s=71eb89a64ba620b6c4417fa120148e66) *** ### Webhooks or notifications > [!NOTE] > > Payrails uses provider webhooks or notifications to receive asynchronous > payment status updates. > [!WARNING] > > 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** 1. Send the Payrails notification URL to Kueski, and ask them to set it as the notification URL for your account. 2. 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](https://docs.payrails.com/reference/authorizeaction.md), 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](https://docs.payrails.com/docs/orchestration/meta-fields.md). | 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 1. Run a test Kueski Pay payment in the Kueski testing environment. 2. Verify that: * Your customer is redirected to Kueski and back to your site. * The payment status updates correctly in Payrails. 3. Once verified in test mode, repeat the setup in live mode. → Continue to: [Test a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md) ## Related topics - [Payment providers](https://docs.payrails.com/docs/integrations/payment-providers.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.