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

# Payment requests

> Request and collect payments from payers through hosted or embedded experiences. Define amount, collect details, and track payments from request to settlement.

A payment request represents a request for funds from a payer.
It defines the **amount**, **currency**, and optional **payer**, and provides a way to collect payment through a **hosted page** or **embedded element**.

Payment requests are the core object for collecting funds in Acclaim.

***

## How payment requests work

Payment requests follow a simple flow: **create**, **collect**, **pay**, and **track**.

1. **Create a payment request**
   Define the amount, currency, and optionally the payer and available payment methods.

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

3. **Payer completes the payment**
   The payer selects a payment method and submits payment.

4. **Track and reconcile**
   Monitor status, receive webhooks, and match the payment to your internal records.

***

## Hosted vs embedded

Payment requests can be fulfilled through two integration models:

### Hosted pages

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

Use hosted pages to:

* Send payment links via email, SMS, or other channels
* Launch quickly with minimal integration
* Offload UI, validation, and compliance handling

***

### Embedded elements

**Embedded elements** allow you to integrate payment collection directly into your application.

Use embedded elements to:

* Maintain full control over the user experience
* Embed payment forms within your product
* Customize flows while relying on Acclaim for processing

***

## Creating payment requests

You can create payment requests using:

* **API** — programmatically create and manage requests
* **Console** — create and manage payments on behalf of payers

Once created, the payment request can be:

* Presented immediately
* Shared via a hosted link
* Embedded in your application

***

## Payment request details

A payment request typically includes:

* **Amount and currency**
* **Payer (optional)**
* **Allowed payment methods**
* **Metadata for internal tracking**

Additional fields may be required depending on the **payment method** and **region**.

***

## Payment methods

Payment methods determine how the payer can complete the payment.

Examples include:

* Cards
* Bank debit methods
* Local payment methods

Available methods vary by country and currency. See **Payment methods** for more.

***

## Payers

A payment request can be associated with a payer, or completed without predefining one.

* Known payer → prefill details and reuse across requests
* Unknown payer → collect details during the payment flow

***

## Status and tracking

Each payment request has a lifecycle and status that reflects its current state.

Statuses typically include:

* Pending or awaiting payment
* Processing
* Succeeded
* Failed

Use webhooks to:

* Track payment completion
* Update internal systems
* Trigger downstream workflows

***

## When to use payment requests

Use payment requests when you need to:

* Collect funds from a payer interactively
* Control the payment experience (hosted or embedded)
* Track payments from request through settlement

For other collection models:

* Use **virtual accounts** to receive bank transfers
* Use **setup requests** to collect payment details for future use

***

## Best practices

* **Define clear amounts and currency upfront**
* **Limit payment methods** to those relevant for the payer’s region
* **Use hosted pages** for fast implementation
* **Use embedded elements** for full UX control
* **Leverage webhooks** for real-time updates

***

## Summary

* Payment requests are the core object for collecting funds
* They define what is being paid and how payment is collected
* Hosted and embedded experiences handle payer interaction
* Every payment is tracked from request to completion