---
id: integration-parameters
title: Integration parameters
summary: Every field of update_checkout_integration and what the runtime does with it.
faces: ["public", "agent"]
personalises: ["integration_name"]
section: shared
group: Configure
order: 50
---
# Integration parameters

An integration is one named way you take payments. `default` and `hosted_page` exist from sign-up;
the console (or the `update_checkout_integration` tool in chat) sets:

| field | values | runtime behaviour |
|---|---|---|
| `allowed_origins` | exact origins | a session created from any other origin answers `origin_not_allowed` |
| `theme` | `light` / `dark` / `auto` | `auto` follows `prefers-color-scheme` |
| `mode` | `auto` / `test` | `test` forces the simulated form |
| `amount_trust_policy` | `allow_unverified` / `require_verified` | unverified amounts render the pre-pay disclosure and a "Reserve" button, or are refused |
| `hold_duration_days` | 1–5, default 5 | the authorised copy: "{merchant} will confirm within N days" |
| `signals_capture_enabled` | boolean, default on | behavioural signals ride the confirm body; off = no listeners, no storage |
| `confirmation_behaviour` | `show_confirmation` / `resolve_only` | `resolve_only` resolves `collect()` without the rendered state (the hosted page ignores it) |
| `confirmation_url` | an absolute `https://` URL, or unset | after a paid or authorised outcome the shopper is taken there; a session may override it; unset leaves them on ripper's confirmation |
| `defaults` | amount, currency, items | used when the page passes none |
| `presentation` | brand, layout, copy, extensions, custom_css | see Layout |

Selecting an integration for a call:

```js run id=params-integration
const result = await ripper.collect({ amount: 4200, currency: 'GBP', integration: 'default' });
```

## Your confirmation page

Set `confirmation_url` and the checkout takes the shopper to your own page once the payment is paid or
authorised. Two query parameters are added, and only these two:

```
https://shop.example/thanks?payment_id=pay_8f3k20a4b1c2d3e4f5a6b7c8&order_reference=ORD-1042
```

`order_reference` is absent when the session has none. Nothing else travels in the URL — no email, no
card detail, no session secret. Look the order up on your server from the payment ID or your own
reference; never trust the query alone as proof of payment.

The URL must be absolute `https://`, at most 512 characters, with no credentials, no `#fragment`, and
neither `payment_id` nor `order_reference` already in its query — the checkout appends those two and will
not overwrite yours. Saving anything else is refused; if such a URL ever reached the checkout it would be
ignored and the shopper would stay on ripper's confirmation.

A session your server creates can carry its own confirmation URL, and it wins over the integration's —
useful when one integration serves several shops or one checkout needs a different landing page.

**Ours is the fallback.** A browser gives no signal that a navigation succeeded, so if the page has not
left within about a second the checkout keeps the shopper where they are and shows a **Continue to
{shop}** link, a ten-second countdown and a **Stay on this page** control that stops it for good. A slow
confirmation page can therefore show that panel for a moment before it lands — that is deliberate, and
better than a shopper left on a page that has stopped talking to them.

Two cases never redirect: `confirmation_behaviour: resolve_only` (your page owns the outcome), and a
shopper who comes **back** to the checkout after paying — pressing Back must not throw them forwards
again.