# Deposit requests

A deposit request is a customer request to deposit funds into their account.
Customers make deposits using deposit forms.

To integrate a deposit form into your website, see [Integrate a deposit form](/docs/dev-docs/integrate-a-deposit-form), [Integrate an express deposit form](/docs/dev-docs/integrate-an-express-deposit), or [Integrate a cashier form](/docs/dev-docs/integrate-a-payout-form).

## Deposit request components

A deposit request contains the following:

- **Customer**: Customer who is making the deposit.
- **Amount and currency**: Requested deposit amount and currency.
The deposit form displays amounts that are determined by a [deposit amount strategy](#deposit-amount-strategies), or amounts that are specified when the deposit request is created.
- **Transactions**: Deposit transactions created when the customer initiates or retries payment.
A deposit request can reference multiple deposit transactions.
For example, declined attempts followed by a successful retry.
At most one deposit transaction is approved.
- **Custom properties**: Optional fields collected from the customer in the deposit form.
Custom properties are rendered in deposit forms.
For more information, see [Custom property sets](#custom-property-sets).
- **Custom fields**: Optional metadata specified when the deposit request is created.
Custom fields are not displayed in the deposit form.
Custom field values are copied to each deposit transaction when matching custom fields exist on both the deposit request and transaction.
Custom fields match when they have the same name and type.
For more information, see the [`customFields` field in the deposit request schema](/catalog/all/deposits/postdepositrequest#deposits/postdepositrequest/t=response&c=201&path=customfields).
- **Redirect URL**: URL to redirect the customer to when the deposit request is completed.
If not specified, the default value is the website URL.
- **Notification URL**: URL where a server-to-server `POST` notification is sent when the deposit transaction result is finalized.


## Deposit request lifecycle

This section describes the lifecycle of a deposit request.

### Deposit request status

The following are all deposit request status types.

| Status  | Description |
|  --- | --- |
| `created` | A deposit request is created, but the customer has not visited the deposit form.
This is a temporary state. |
| `pending` | A customer visits the deposit form but has not initiated a deposit transaction.
This is a temporary state. |
| `initiated` | A customer initiates a deposit transaction.
This is a temporary state. |
| `attempted` | A payment gateway declines a deposit transaction attempt.
This is a temporary state. |
| `completed` | A payment gateway approves a deposit transaction.
This is a permanent state. |
| `expired` | A deposit request expires without an approved deposit transaction.
The default expiration time is one hour from deposit request creation.
This is a permanent state. |


### Deposit request created and completed

This section describes the lifecycle for a deposit request that is completed.

```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
graph LR;
    A(1 Created) --> B(2 Pending)
    B --> C(3 Initiated)
    C --> D(4 Completed)
```

1. A deposit request is created using the [Create a deposit request](/catalog/all/deposits/postdepositrequest#deposits/postdepositrequest) API operation and assigned the `created` status.
2. The customer visits the deposit form.
The deposit request transitions to `pending`.
3. The customer selects an amount and payment method, and initiates a deposit transaction.
The deposit request transitions to `initiated`.
4. The deposit transaction is approved, and the deposit request transitions to `completed`.


### Deposit request attempted and retried

This section describes the lifecycle for a deposit request where the payment gateway declines a deposit transaction and the customer retries.

1. A deposit request is created and assigned the `created` status.
2. The customer visits the deposit form.
The deposit request transitions to `pending`.
3. The customer initiates a deposit transaction.
The deposit request transitions to `initiated`.
4. The deposit transaction is declined.
The deposit request transitions to `attempted`.
5. The customer retries with a different payment method or amount.
Rebilly creates another deposit transaction, and the deposit request transitions to `initiated`.
6. The deposit transaction is approved, and the deposit request transitions to `completed`.


### Deposit request expired

This section describes the lifecycle for a deposit request that expires.

1. A deposit request is created and assigned the `created` status.
2. The customer does not visit the deposit form, or visits but does not complete an approved deposit transaction.
3. The expiration time is reached, and the deposit request transitions to `expired`.


## Deposit amount strategies

Deposit amount strategies determine which amounts are displayed to the customer in a deposit form.
Use strategies to configure amounts based on currency, customer segmentation, or prior deposit behavior.

A deposit amount strategy contains the following:

- **Amounts**: Configuration for how amounts are calculated, including a base amount and increments.
The calculator can be `absolute` or `percent`.
Optionally, the base amount adjusts to the customer's last deposit amount.
- **Custom amount**: Optional restrictions for custom amounts that a customer can enter, including minimum, maximum, and increment values.
If this value is `null`, custom amounts are prohibited.
- **Filter**: An optional filter that determines if the strategy applies to a deposit request based on its properties, such as currency.
- **Priority**: A non-negative integer that determines which deposit amount strategy is applied when more than one matches.
The deposit amount strategy with the highest priority value is applied.
If the `strategyId` property is specified when a deposit request is created, the specified deposit amount strategy is applied and all other deposit amount strategies are ignored.


Available operations:

- [Create a deposit amount strategy](/catalog/all/deposits/postdepositstrategy#deposits/postdepositstrategy)
- [Retrieve deposit amount strategies](/catalog/all/deposits/getdepositstrategycollection#deposits/getdepositstrategycollection)
- [Retrieve a deposit amount strategy](/catalog/all/deposits/getdepositstrategy#deposits/getdepositstrategy)
- [Update a deposit amount strategy](/catalog/all/deposits/putdepositstrategy#deposits/putdepositstrategy)
- [Delete a deposit amount strategy](/catalog/all/deposits/deletedepositstrategy#deposits/deletedepositstrategy)


## Custom property sets

Custom property sets extend the deposit form with additional customer-facing fields.
Use custom property sets to collect information from the customer during the deposit request process.
The collected information is stored on the deposit request.

Available operations:

- [Create a custom deposit property set](/catalog/all/deposits/postdepositcustompropertyset#deposits/postdepositcustompropertyset)
- [Retrieve custom deposit property sets](/catalog/all/deposits/getdepositcustompropertysetcollection#deposits/getdepositcustompropertysetcollection)
- [Retrieve a custom deposit property set](/catalog/all/deposits/getdepositcustompropertyset#deposits/getdepositcustompropertyset)
- [Upsert a custom deposit property set](/catalog/all/deposits/putdepositcustompropertyset#deposits/putdepositcustompropertyset)
- [Delete a custom deposit property set](/catalog/all/deposits/deletedepositcustompropertyset#deposits/deletedepositcustompropertyset)


## Webhooks

Transaction webhooks are sent to webhook subscribers when the result of a deposit transaction is finalized.
For more information, see [Webhook configuration](/docs/dev-docs/webhooks-configuration).

Customer timeline messages also record deposit request status changes.
Examples of timeline message types are `deposit-request-created`, `deposit-request-started`, `deposit-request-completed`, and `deposit-request-expired`.
These types align with the deposit request lifecycle described in this topic.
For more information, see [Retrieve customer timeline messages](/catalog/all/customers-timeline/getcustomertimelinecollection).

## Related topics

- [Integrate a deposit form](/docs/dev-docs/integrate-a-deposit-form)
- [Integrate an express deposit form](/docs/dev-docs/integrate-an-express-deposit)
- [Integrate a cashier form](/docs/dev-docs/integrate-a-payout-form)
- [Deposits API operations](/catalog/all/deposits/)