> ## 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.

# Variables and placeholders

> Reference for the placeholders available to build the request body, headers, and status check of a custom gateway.

When building the request to the PSP—body, headers, and status check—you can use `{{...}}` placeholders. Jelou replaces them at runtime with the real charge data.

## Available placeholders

| Placeholder | Description |
| - | - |
| `{{credentialKey}}` | Any `key` you declared in the wizard's **Credentials** step. |
| `{{amount}}` | Flat total charge amount. |
| `{{currency}}` | Charge currency (e.g. `USD`). |
| `{{description}}` | Charge description. |
| `{{order.id}}` | Jelou's internal order id. |
| `{{order.reference_id}}` | External reference id for the order. |
| `{{order.metadata}}` | Object with additional order metadata. Inserted unquoted into the JSON, as an object. |
| `{{order.non_taxable_amount}}` | Non-taxable portion (tax breakdown). |
| `{{order.taxable_amount}}` | Taxable portion (tax breakdown). |
| `{{order.tax}}` | Applied tax amount. |
| `{{order.tax_percentage}}` | Derived tax percentage (`tax / taxable_amount * 100`). |
| `{{customer.reference_id}}` | Customer's internal identifier. |
| `{{customer.phone}}` | Customer's phone. |
| `{{customer.email}}` | Customer's email. |
| `{{customer.full_name}}` / `{{customer.middle_name}}` / `{{customer.surname}}` | Customer's name. |
| `{{customer.legal_id_type}}` / `{{customer.legal_id}}` | ID document (national ID, tax ID, etc.). |
| `{{customer.address}}` | Customer's address. |
| `{{customer.country}}` | Customer's country. |
| `{{returnUrl}}` | Return URL after checkout. Resolves to Jelou's own callback if you configured **Check status with the PSP on return**; otherwise it resolves to the return URL sent by the API consumer. |
| `{{webhookUrl}}` | The gateway's own webhook URL — useful if your PSP accepts configuring the callback inline in the same charge-creation payload. |
| `{{expiration.duration_seconds}}` / `{{expiration.duration_minutes}}` / `{{expiration.expires_at_unix}}` / `{{expiration.expires_at_unix_ms}}` / `{{expiration.expires_at_iso8601}}` | Checkout validity window. |

> [!NOTE]
>
> Checkout validity is fixed to a **30-hour** window from creation — it isn't configurable per gateway or per request yet.

Inside **Check status with the PSP on return** (and only there) `{{transaction_id}}` is also available. Use it in the URL, headers, or body of that request; without it, the status check wouldn't distinguish between transactions.

## Example `body_template`

```json title="Example body_template" theme={null}
{
  "amount": {{amount}},
  "currency": "{{currency}}",
  "description": "{{description}}",
  "reference": "{{order.reference_id}}",
  "customer": {
    "name": "{{customer.full_name}}",
    "email": "{{customer.email}}",
    "phone": "{{customer.phone}}"
  },
  "api_key": "{{apiKey}}",
  "callback_url": "{{webhookUrl}}"
}
```

In this example, `{{apiKey}}` is a credential declared in the wizard's **Credentials** step; the rest are system placeholders listed above.

## Conditional sections

The body template also supports simple conditional inclusion (no nesting or loops), useful for omitting fields with no value:

* `{{#field}}...{{/field}}` — includes the content if `field` has a truthy value.
* `{{^field}}...{{/field}}` — includes the content if `field` is falsy or empty.

## Validation rules

* Any `{{...}}` that isn't on this page, isn't a declared credential, or (only in status check) `{{transaction_id}}`, is treated as an **unknown placeholder**.
* An unknown placeholder blocks saving in the wizard and in the backend.

> [!WARNING]
>
> If your body uses `{{returnUrl}}` and you did **not** enable status verification on return, every charge request must explicitly include the return URL, or Jelou rejects it.

## Next steps

> [card] [Create a custom gateway](https://docs.jelou.ai/en/guides/integrations/payments/custom/create-gateway.md)
>
> Go back to the 6-step wizard to apply these placeholders.

> [card] [Test the gateway](https://docs.jelou.ai/en/guides/integrations/payments/custom/test-gateway.md)
>
> Check how your placeholders render before going to production.


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