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

# Setup requests

> Collect and securely store payment details for future use. Save payment methods through hosted or embedded experiences without initiating a payment.

A setup request collects and securely stores a payer’s payment details for future use.
It allows you to save a **payment method as a token** without initiating a payment.

Setup requests are used when you need to **charge later**, **reuse payment methods**, or support **off-session payments**.

***

## How setup requests work

Setup requests follow a simple flow: **create**, **collect details**, **store**, and **reuse**.

1. **Create a setup request**
   Define the payer (optional) and supported payment methods.

2. **Present the collection experience**
   Use a **hosted page** or **embedded element** to collect payment details.

3. **Payer submits details**
   The payer provides payment method information (e.g. card or bank details).

4. **Store payment method**
   The payment method is securely stored as a token and can be used in future payment flows.

***

## Hosted vs embedded

Setup requests can be fulfilled through two integration models:

### Hosted pages

A **hosted page** is a secure, Acclaim-managed page accessed via a link.

Use hosted pages to:

* Collect payment details without building UI
* Share links via email or messaging
* Ensure secure handling of sensitive data

***

### Embedded elements

**Embedded elements** allow you to collect payment details directly within your application.

Use embedded elements to:

* Control the user experience
* Embed secure payment forms
* Maintain a consistent product flow

***

## What is stored

When a setup request is completed:

* Payment details are **securely stored and tokenized**
* Sensitive data is **not exposed to your systems**
* A **payment method token** is returned for future use

This token can be used to:

* Create future payment requests
* Initiate payments without re-collecting details

***

## Relationship to payment requests

* **Setup requests** collect and store payment details
* **Payment requests** collect funds

You can combine both flows:

1. Save a payment method
2. Use the stored method in a future payment request

***

## Payment methods

Setup requests support payment methods that can be stored for reuse.

Examples include:

* Cards
* Bank debit methods

Supported methods vary by country and currency.

***

## Payers

A setup request can optionally be associated with a payer.

* Known payer → store and reuse payment methods
* Unknown payer → collect and associate during the flow

***

## Status and tracking

Each setup request has a lifecycle and status.

Statuses typically include:

* Pending or awaiting completion
* Completed
* Failed

Use webhooks to:

* Track completion
* Store tokens in your system
* Trigger follow-up workflows

***

## When to use setup requests

Use setup requests when you need to:

* Collect payment details without charging immediately
* Support future or recurring payments
* Enable off-session payments
* Reduce friction for repeat payers

***

## Best practices

* **Save once, reuse many times**
* **Associate tokens with payers** for easier reuse
* **Limit supported payment methods** to relevant options
* **Use webhooks** to capture completion events

***

## Summary

* Setup requests collect and store payment details for future use
* No funds are moved during saving payment methods
* Payment methods are stored as secure tokens
* Tokens can be reused in future payment flows