Components Integration

The Acquired Components payment UI can be linked directly to a subscription. When you include a subscription_id in the Components /payment-sessions request, the session inherits configuration from the subscription, captures the customer's card, and automatically activates the subscription on completion — all in one step.

📘
Components is only used for the initial activation payment. All subsequent recurring payments are handled automatically by the billing engine — no further Components involvement is needed.

How it works

Create a subscription without payment methods — it is created as incomplete.
Create a Components session with the subscription_id — session configuration is inherited from the subscription.
Customer completes the Components payment UI — their card is saved and verified.
Subscription is activated automatically — the card_id is added as the payment method and the subscription transitions to active.

Creating a session with a subscription

Include the subscription_id in your /payment-sessions request. The subscription must be in incomplete status and belong to the same merchant as the authenticated session.

POST /payment-sessions request:

{
  "subscription_id": "01HNY4G8G5ZMAXQB8T0Z1Y1ZMW",
  "transaction": {
    "order_id": "order_abc123"
  },
  "tds": {
    "redirect_url": "https://example.com/3ds-redirect",
    "webhook_url": "https://example.com/webhooks/3ds"
  },
  "webhook_url": "https://example.com/webhooks/payments"
}

When a subscription_id is present, many fields are automatically inherited from the subscription and its linked customer record. You only need to supply session-specific fields like order_id, redirect URLs, and webhook URLs.

Parameter inheritance

When a subscription_id is present, each parameter in the Components session request follows one of three behaviours:

Behaviour	Description
Inherit	Value is read from the subscription or customer record. If you also supply this field, it must match — a mismatch returns HTTP 400.
Derive	Value is computed by the server from the subscription configuration. You must not supply this field — doing so returns HTTP 400.
Accept	Value is accepted from your request as-is. No upstream default exists, or the field is intentionally session-scoped.

Transaction parameters

Parameter	Behaviour	Notes
`transaction.order_id`	Accept	You must supply the `order_id` for the initial payment.
`transaction.amount`	Inherit	Inherited from the subscription price. Rejected if supplied and mismatched.
`transaction.currency`	Inherit	Inherited from the subscription price. Rejected if supplied and mismatched.
`transaction.capture`	Derive	Derived from subscription trial configuration (see Capture flag below). Rejected if supplied explicitly.
`transaction.moto`	Accept	Passed through as-is.
`transaction.custom_data`	Accept	Inherited from the subscription if not supplied. Can be overridden per-session.
`transaction.custom1`	Accept	Inherited from the subscription if not supplied. Can be overridden per-session.
`transaction.custom2`	Accept	Inherited from the subscription if not supplied. Can be overridden per-session.

Customer parameters

Parameter	Behaviour	Notes
`customer.customer_id`	Inherit	Inherited from the subscription's linked customer. Rejected if mismatched.
`customer.reference`	Inherit	Inherited from the customer record. Rejected if conflicting.
`customer.name`	Inherit	Inherited from the customer record. Rejected if conflicting.
`customer.dob`	Inherit	Inherited from the customer record. Rejected if conflicting.
`customer.custom_data`	Inherit	Inherited from the customer record. Rejected if conflicting.
`customer.billing.*`	Inherit	Inherited from the customer record. Rejected if conflicting.
`customer.shipping.*`	Inherit	Inherited from the customer record. Rejected if conflicting.

Session parameters

Parameter	Behaviour	Notes
`tds.redirect_url`	Accept	Must be provided in the request.
`tds.webhook_url`	Accept	Must be provided in the request.
`webhook_url`	Accept	Must be provided in the request. Persisted to the subscription for use in recurring payments.
`save_card`	Derive	Enforced as `true`. Returns 400 if explicitly set to `false`.
`is_recurring`	Derive	Enforced as `true`. Returns 400 if explicitly set to `false`.
`payment_methods`	Accept	Accepted, but `pay_by_bank` must not be included. Returns 400 if present.

Capture flag

The capture flag is automatically derived from the subscription's trial configuration. You cannot set it explicitly when subscription_id is present.

Condition	Capture value	Payment behaviour
No trial (`trial_end` is null)	`true`	Full payment — charge the subscription amount immediately.
Active trial (`trial_end` is in the future)	`false`	Auth-only — zero-value authorisation to verify the card. No funds are collected.

What happens on session completion

When the Components session completes successfully:

Card is saved — the customer's card_id is stored as the subscription's payment method.
Subscription is activated — the subscription transitions from incomplete to active.
Transaction is linked — the transaction_id from the Components session is recorded against the subscription's payment method.
Webhook URL is stored — the webhook_url from the session is persisted to the subscription and used for status update callbacks on all future recurring payments.
First bill is created — billing begins automatically based on the subscription's price and cycle configuration.

With a free trial

If the subscription has an active trial period (trial_end in the future), the Components session performs a zero-value authorisation only. The subscription is activated, but the first bill's due date is set to the trial_end date. No funds are collected until the trial expires.

Without a free trial

If the subscription has no trial period, the Components session performs a full payment for the subscription amount. The first bill is created with status paid immediately, and the next bill is scheduled according to the billing cycle.

Validation rules

The following validations are enforced when subscription_id is present:

The subscription must be in incomplete status.
The subscription must belong to the same merchant/company as the authenticated session.
save_card and is_recurring must not be explicitly set to false.
transaction.capture must not be supplied — it is derived automatically.
pay_by_bank must not be included in payment_methods.
Inherited fields (amount, currency, customer_id, etc.) must match if supplied — mismatches return HTTP 400.