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.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.
How setup requests work
Setup requests follow a simple flow: create, collect details, store, and reuse.- Create a setup request Define the payer (optional) and supported payment methods.
- Present the collection experience Use a hosted page or embedded element to collect payment details.
- Payer submits details The payer provides payment method information (e.g. card or bank details).
- 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
- 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
- Save a payment method
- 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
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
- 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