> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom gateway

> Configure the 6-step wizard, step by step, to set up a custom payment provider in Payments.

From **Payments → Integrations**, the **Add gateway** button opens the setup wizard. When creating a new gateway, steps are **linear**: you must complete each one before moving on. Once the gateway exists, you can move freely between steps to edit it.

> [!TIP]
>
> Before filling the wizard, use the [compatibility prompt](https://docs.jelou.ai/en/guides/integrations/payments/custom/compatibility-prompt.md) with your LLM and your PSP's documentation. You leave with the mapping ready for each step.

## Setup wizard

**1. General**

Set the **Name**, **Slug**, **Description** (optional), **Icon URL** (optional), and **Environment** (**Sandbox** or **Production**).

* **Name** and **Slug** are required.

![General step of the custom gateway wizard, with the Name, Slug, Environment, and Description fields](https://mintcdn.com/jelouai/R4qL5d7Hj6fxJl87/assets/images/integraciones/pagos/personalizadas/wizard-paso-1-general.png?fit=max\&auto=format\&n=R4qL5d7Hj6fxJl87\&q=85\&s=c052bdf8391acc67737f2e862558d611)

Wizard step 1: the gateway's general information

> [!TIP]
>
> Start in **Sandbox**. Environment can't be changed later: for production you'll create another gateway (or a separate setup) with real keys.

> [!WARNING]
>
> **Slug** and **Environment** can't be edited after the gateway is created.

**2. Credentials**

Declare each secret or API key your PSP needs. For each row you define:

* **Key** — internal placeholder name (for example `apiKey`)
* **Label** — text shown in the UI
* **Type** — **Text** or **Secret**

You must declare at least one credential. Use **Secret** for API keys and tokens: the value stays masked.

![Credentials step of the custom gateway wizard, with a Secret-type credential row](https://mintcdn.com/jelouai/R4qL5d7Hj6fxJl87/assets/images/integraciones/pagos/personalizadas/wizard-paso-2-credenciales.png?fit=max\&auto=format\&n=R4qL5d7Hj6fxJl87\&q=85\&s=d962d12e3e07e77a54b07b7ba038a5ce)

Wizard step 2: credentials your PSP needs

> [!TIP]
>
> Here you only **declare** which keys exist (like the fields in a BYOK form). You paste the real values later, in **Connect**.

> [!NOTE]
>
> You can't mark a credential as required from this screen. If you need that behavior, coordinate with your technical team.

**3. Request (includes Return)**

Here you define how Jelou calls the PSP to create a charge and, optionally, how to handle the customer's return.

**Request**

* **Method** (GET, POST, PUT, or PATCH) and **URL** of the charge-creation endpoint
* **Headers** — for example `Authorization: Bearer {{myCredential}}`
* **Body template** — request JSON with `{{...}}` placeholders (see [Variables and placeholders](https://docs.jelou.ai/en/guides/integrations/payments/custom/variables-and-placeholders.md))
* **Payment link path** and **Transaction id path** — path in the response JSON where the checkout URL and transaction id live (for example `data.checkout_url`)

![Request step of the custom gateway wizard, with the endpoint, headers, and sample body template](https://mintcdn.com/jelouai/R4qL5d7Hj6fxJl87/assets/images/integraciones/pagos/personalizadas/wizard-paso-3-peticion.png?fit=max\&auto=format\&n=R4qL5d7Hj6fxJl87\&q=85\&s=79bc77d61b91153e03d30c7b153e4b09)

Wizard step 3: endpoint, headers, and body template for the request

**URL** and **Body template** are required. Every `{{...}}` must match a declared credential or a recognized placeholder.

**Return (optional)**

* **Transaction id parameter** — query param the PSP adds when redirecting after checkout
* **Check status with the PSP on return** — active status lookup (method, URL, headers, paths, and mapping to **Success / Failed / None**)

![Return block of the wizard, with browser return and PSP status check toggles enabled](https://mintcdn.com/jelouai/R4qL5d7Hj6fxJl87/assets/images/integraciones/pagos/personalizadas/wizard-paso-3-retorno-navegador.png?fit=max\&auto=format\&n=R4qL5d7Hj6fxJl87\&q=85\&s=9859c01eed40670045d927c0e715ede7)

Return block: enable browser return and status check with the PSP

![Status mapping table from PSP values to Success or Failed inside the return block](https://mintcdn.com/jelouai/R4qL5d7Hj6fxJl87/assets/images/integraciones/pagos/personalizadas/wizard-paso-3-mapeo-estados.png?fit=max\&auto=format\&n=R4qL5d7Hj6fxJl87\&q=85\&s=0cd17ec9ca561c2134bfb1d1dc2a3bf7)

Mapping each PSP status value to Success, Failed, or None

> [!WARNING]
>
> Confirming this step creates or updates the gateway. **Slug** and **Environment** are locked in. If creation fails, the wizard blocks progress.

> [accordion] Notes on the HTTP method
>
> The selector may show **DELETE**, but only GET, POST, PUT, or PATCH are accepted. Choosing DELETE causes the save to fail.

**4. Connect**

Available after the previous step is saved. Enter the **real values** for each declared credential—your PSP's secrets, not their names.

![Connect step of the custom gateway wizard, with the Api key field and Update keys button](https://mintcdn.com/jelouai/R4qL5d7Hj6fxJl87/assets/images/integraciones/pagos/personalizadas/wizard-paso-4-conectar.png?fit=max\&auto=format\&n=R4qL5d7Hj6fxJl87\&q=85\&s=9ecda7f1709d7e1e4eec1295b5fe7412)

Wizard step 4: real values for the declared credentials

> [!TIP]
>
> In **Sandbox**, paste the PSP's test keys. In **Production**, the real keys. Without this step, the gateway can't authenticate with the provider.

**5. Webhook**

Configure how to interpret inbound notifications from the PSP:

* Enable or disable the webhook with **Enabled**. If you disable it, the wizard skips to Finish.
* **Signature header** (optional) — header where the PSP sends its HMAC signature
* **Event name path** and **Transaction id path** — paths inside the payload
* **Events table** — map each PSP event to **Success**, **Failed**, or **None**

![Webhook step of the custom gateway wizard, with the signature header, payload paths, and expected JSON format](https://mintcdn.com/jelouai/R4qL5d7Hj6fxJl87/assets/images/integraciones/pagos/personalizadas/wizard-paso-5-webhook.png?fit=max\&auto=format\&n=R4qL5d7Hj6fxJl87\&q=85\&s=9db7a6796397d76be0269c73bbd13815)

Wizard step 5: confirmation webhook configuration

> [!NOTE]
>
> The **Expected JSON format** field is only a visual reference—it isn't sent to the backend.

**6. Webhook secret**

Only appears if the webhook is enabled. Copy the **Webhook URL** the wizard generates, configure it in your PSP's dashboard, and generate or rotate the **HMAC secret**.

* Available algorithms: **SHA256**, **SHA384**, or **SHA512**
* A custom secret must be at least **16 characters**

![Webhook secret step of the custom gateway wizard, with the webhook URL, active secret, and signature algorithm selector](https://mintcdn.com/jelouai/R4qL5d7Hj6fxJl87/assets/images/integraciones/pagos/personalizadas/wizard-paso-6-webhook-secret.png?fit=max\&auto=format\&n=R4qL5d7Hj6fxJl87\&q=85\&s=87a8f432b1434a7d0bc9bd82d6df85f0)

Wizard step 6: webhook URL and signing secret

Finishing this step closes the wizard.

> [!TIP]
>
> Before using the gateway in production, use **Test** from the Integrations list. See [Test the gateway](https://docs.jelou.ai/en/guides/integrations/payments/custom/test-gateway.md).

## Next steps

> [card] [Variables and placeholders](https://docs.jelou.ai/en/guides/integrations/payments/custom/variables-and-placeholders.md)
>
> Placeholders available for the body, headers, and status check.

> [card] [Test the gateway](https://docs.jelou.ai/en/guides/integrations/payments/custom/test-gateway.md)
>
> Generate a test paylink before going to production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.